Focus - FLL (2004)

FOCUS.
FLL
A Library for Visual FoxPro
Reference Guide
Version 8.10
FastWrite s.c.r.l.
Rue Amédé Bracke, 9
1950 Kraainem
Belgium
Tel.: +32-2-720.82.28
Fax: +32-2-720.79.30
Internet: http://www.fastwrite.com
Email: techsupp@fastwrite.com
Table Of Contents
Table Of Contents
ARRAY FUNCTIONS...............................................................................................................................................................37
ARR_average() : Returns the average of all numeric elements contained in an array.................................................................38
ARR_Create() : Creates an array of given dimensions............................................................................................................38
ARR_Dimensions() : Determines the dimensions of an array (rows and cols)............................................................................39
ARR_elements() : Total number of elements in an array........................................................................................................40
ARR_columns() : Number of columns in an array..................................................................................................................40
ARR_IsArray() : Determines if a variable is an array.............................................................................................................41
ARR_max() : Returns the biggest numeric value of all elements contained in an array...............................................................41
ARR_min() : Returns the smallest numeric value of all elements contained in an array...............................................................41
ARR_rows() : Number of rows in an array...........................................................................................................................42
ARR_LastVersion() : Returns the file stamp of ARR_*() functions............................................................................................42
BMP FUNCTIONS..................................................................................................................................................................44
BMP_bits() : Number of bits per pixel..................................................................................................................................45
BMP_colors() : Number of colors in the bitmap file...............................................................................................................45
BMP_header() : Reads a bitmap file header..........................................................................................................................45
BMP_height() : Returns bitmap height.................................................................................................................................46
BMP_isbmp() : Tests whether a file is a bitmap file...............................................................................................................46
BMP_LastVersion() : Returns the file stamp of BMP functions.................................................................................................47
BMP_width() : Returns bitmap width...................................................................................................................................47
CD FUNCTIONS....................................................................................................................................................................49
CD_bayope() : Opens the door and ejects CD media (if possible)...........................................................................................51
CD_bayclo() : Retracts the tray and closes the door bay (if possible)......................................................................................51
CD_caneje() : Can CD audio device eject the media?............................................................................................................51
CD_canpla() : Can CD audio device play the media?.............................................................................................................51
CD_close() : Closes CD device...........................................................................................................................................52
CD_command() : Sends a MCI command string to the CD device open with CD_open().............................................................52
CD_curpos() : Returns the current position..........................................................................................................................52
CD_curtra() : Returns the current track...............................................................................................................................52
CD_end() : Moves to the end of audio data on the disc..........................................................................................................53
CD_home() : Moves to the start of audio data on the disc......................................................................................................53
CD_iscd() : Is a CD-ROM attached to the computer?.............................................................................................................53
CD_LastError() : Determines the last error that occurred within the CD_*() functions................................................................54
CD_LastVersion() : Returns the file stamp of CD_*() functions...............................................................................................54
CD_loff() : Disables output to the left audio channel.............................................................................................................54
CD_lon() : Enables output to the left audio channel..............................................................................................................55
CD_MediaPresent() : Returns .T. if a disc is inserted in the drive.............................................................................................55
CD_mode() : Returns a value indicating the current mode of the device..................................................................................55
CD_msf() : Sets the current time format to MSF (minutes, seconds, frames)............................................................................56
CD_ms() : Sets the current time format to MS (milliseconds).................................................................................................56
CD_off() : Disables audio output (mute)..............................................................................................................................56
CD_on() : Enables audio output (unmute)...........................................................................................................................57
CD_open() : Opens CD device............................................................................................................................................57
CD_pause() : Pauses playing.............................................................................................................................................57
CD_play() : Plays CD tracks...............................................................................................................................................57
CD_ready() : Determines whether the CD is ready................................................................................................................58
CD_resume() : Resumes playback......................................................................................................................................58
CD_roff() : Disables output to the right audio channel...........................................................................................................58
CD_ron() : Enables output to the right audio channel............................................................................................................59
CD_seek() : Moves to the specified position.........................................................................................................................59
CD_start() : Positions the disc at the starting position...........................................................................................................59
CD_stop() : Stops playback...............................................................................................................................................59
CD_time() : Returns the current time format........................................................................................................................60
CD_tmsf() : Sets the current time format to TMSF................................................................................................................60
CD_totlen() : Returns the total length of disc.......................................................................................................................60
CD_tottra() : Returns the number of tracks on the disc..........................................................................................................60
CD_tralen() : Returns the length of a given track..................................................................................................................61
CD_trapos() : Returns the starting position of a given track...................................................................................................61
CLIPBOARD FUNCTIONS.........................................................................................................................................................62
CLP_CountFormats() : Counts the number of different data formats available in the clipboard....................................................63
CLP_empty() : Clears the Windows clipboard.......................................................................................................................63
CLP_GetText() : Gets text from Windows clipboard...............................................................................................................63
CLP_IsFormatAvailable() : Determines whether the clipboard contains data in the specified format.............................................64
CLP_LastVersion() : Returns the file stamp of CLP functions...................................................................................................65
CLP_SetText() : sets text into the Windows clipboard............................................................................................................65
COM FUNCTIONS.................................................................................................................................................................66
COM_BuildCommDCB() : Fills the internal DCB structure of one of the COM handles of FOCUS with the specified values................69
COM_close() : to be continued...........................................................................................................................................69
COM_LastVersion() : Returns the file stamp of COM functions................................................................................................69
COM_open() : to be continued...........................................................................................................................................70
COM_read() : to be continued............................................................................................................................................70
FOCUS.FLL Version 8.10

/conversion/tmp/scratch/385945009.doc
Last Revision: 4 August 2004 - 22:44
© 1990-2004 FastWrite Page 2
Table Of Contents
COM_SetCommState() : Configures a communications device according to the specifications found in the FOCUS internal DCB......70
COM_write() : to be continued...........................................................................................................................................70
CURSORS FUNCTIONS............................................................................................................................................................72
CUR_LastVersion() : Returns the file stamp of CUR functions.................................................................................................73
CUR_load() : Creates a cursor based on data contained in a file..............................................................................................73
DATE FUNCTIONS.................................................................................................................................................................74
DAT_bom() : Beginning of the month.................................................................................................................................75
DAT_boy() : Beginning of the year.....................................................................................................................................75
DAT_ctot() : Character to datetime string............................................................................................................................75
DAT_DateTime() : Current date and time (char YYYY-MM-DD hh:mm:ss)................................................................................76
DAT_day() : Returns the numeric day-of-the-month for a given date.......................................................................................76
DAT_doy() : Returns the day-of-the-year of a given date.......................................................................................................76
DAT_eom() : End of the month..........................................................................................................................................77
DAT_eoy() : End of the year..............................................................................................................................................77
DAT_Easter() : Determines the exact date of Easter..............................................................................................................77
DAT_IsLeap() : Is this a leap year?.....................................................................................................................................78
DAT_jtod() : Julian date to date.........................................................................................................................................78
DAT_LastVersion() : Returns the file stamp of DAT functions..................................................................................................78
DAT_month() : Returns the number of the month for a given date..........................................................................................79
DAT_num() : Converts a date into a number (Julian date).....................................................................................................79
DAT_NumberOfDays() : Returns the number of days in a month.............................................................................................80
DAT_stod() : Transforms a YYYYMMDD date string into a FoxPro date (opposite to DTOS()).......................................................80
DAT_year() : Returns the year from the specified date..........................................................................................................80
DAT_ymd() : Splits a date into its basic components.............................................................................................................81
DBF FUNCTIONS..................................................................................................................................................................82
DBF_append() : Appends a new record or a series of records.................................................................................................83
DBF_bot() : Is the table at begin of file?..............................................................................................................................83
DBF_commit() : Flushes current record to disk.....................................................................................................................83
DBF_empty() : Is it an empty table?...................................................................................................................................83
DBF_eot() : Is the table at end of file?................................................................................................................................84
DBF_exclu() : Table open exclusively?................................................................................................................................84
DBF_GoBottom() : Go to the bottom of a given work area.....................................................................................................84
DBF_GoTop() : Go to the top of a given work area...............................................................................................................85
DBF_flockd() : Table locked or open exclusively?..................................................................................................................85
DBF_LastVersion() : Returns the file stamp of DBF functions..................................................................................................85
DBF_lock() : Locks a file or a record...................................................................................................................................86
DBF_readon() : Table open without write access?.................................................................................................................86
DBF_reccnt() : Number of records......................................................................................................................................86
DBF_replac() : Replaces a field with a value.........................................................................................................................87
DBF_rlockd() : Current record locked, table locked or table open exclusively?..........................................................................87
DBF_seek() : Performs a SEEK...........................................................................................................................................87
DBF_Skip() : Skips a specified number of records in a given work area...................................................................................88
DBF_status() : Retrieves the status of a DBF........................................................................................................................88
DATA DRIVEN APPLICATION FUNCTIONS...................................................................................................................................89

DDA_Aliases() : Returns all the aliases that are known for a specified FOCUS.FLL function.........................................................91
DDA_Argc() : Number of arguments that a specified function of FOCUS.FLL expects.................................................................91
DDA_Argv() : Argument types that a specified function of FOCUS.FLL expects..........................................................................92
DDA_count() : Returns the number of Visual FoxPro commands, and evaluations performed by the FOCUS.FLL interpreter engine.. 92
DDA_CloseLog() : Closes the DDA log file............................................................................................................................93
DDA_error() : Last operation internal error code...................................................................................................................94
DDA_Evaluate() : Evaluates an expression...........................................................................................................................94
DDA_ExecFuncPtr() : Executes the code that is pointed to by the internal execution pointer.......................................................95
DDA_Execute() : Executes a command line..........................................................................................................................96
DDA_ExecuteFile() : Executes a set of commands contained in a file.......................................................................................96
DDA_ExecuteSnapIn() : Executes a snap-in file....................................................................................................................97
DDA_ExtendedError() : Last operation Visual FoxPro error code.............................................................................................97
DDA_ExtendedErrorMessage() : Last operation Visual FoxPro error message............................................................................98
DDA_GetLog() : Gets the log file in which commands that couldn’t be executed are logged........................................................99
DDA_GetStop() : Retrieves the current Error Handler routine...............................................................................................100
DDA_FuncPtr() : Returns a function pointer to a specified function contained in FOCUS.FLL......................................................100
DDA_IsFunction() : Returns .T. if a specified function exists in FOCUS.FLL.............................................................................100
DDA_LastVersion() : Returns the file stamp of DDA functions...............................................................................................101
DDA_ResetCounter() : Resets the internal DDA counter to 0.................................................................................................101
DDA_SetExecPtr() : Assigns the internal execution pointer to a given value............................................................................102
DDA_SetLog() : Sets the log file in which commands that couldn’t be executed are logged by the FOCUS engine........................102
DDA_SetStop() : Customizes the Error Handler routine that must be used when execution errors occur.....................................103
DDA_Stop() : Sets the strategy that FOCUS.FLL has to follow whenever there is a execution error............................................103
COMMON DIALOG FUNCTIONS...............................................................................................................................................104

DLG_color() : Selects a color...........................................................................................................................................106
DLG_font() : Selects a font..............................................................................................................................................107
DLG_LastVersion() : Returns the file stamp of DLG functions................................................................................................109
DLG_open() : Open File Dialog Box...................................................................................................................................109
DLG_save() : Presents the Save File Dialog Box..................................................................................................................109

Table Of Contents
EDITOR FUNCTIONS............................................................................................................................................................113
EDI_AutoIndent() : Auto indent flag..................................................................................................................................115
EDI_Backup() : Backup flag.............................................................................................................................................115
EDI_Close() : Closes a file...............................................................................................................................................115
EDI_Cut() : Copies the selected portion of the file to the clipboard and deletes it from the editing window..................................116
EDI_Delete() : Deletes the selected portion of the file..........................................................................................................116
EDI_FileName() : Determines the name of the file that is currently edited..............................................................................116
EDI_Dirty() : Determines whether the file has been changed................................................................................................116
EDI_GetLineNum() : Returns the line number a given offset belongs to..................................................................................117
EDI_GetLinePos() : Returns the offset of the first character of the specified line in the file in the specified editing window............117
EDI_GetPos() : Returns the current offset position..............................................................................................................117
EDI_GroupUndo() : Groups/ungroups undo selection..........................................................................................................118
EDI_Insert() : Inserts a string in the editing window...........................................................................................................118
EDI_LastVersion() : Returns the file stamp of EDI functions.................................................................................................118
EDI_Open() : Opens a file for editing................................................................................................................................119
EDI_Paste() : Copies the contents of the clipboard into the file in the specified editing window.................................................119
EDI_PosInView() : Determines whether a given position is visible in the current view of the editing window...............................119
EDI_Redo() : Redoes the last action..................................................................................................................................120
EDI_Save() : Saves a file................................................................................................................................................120
EDI_Select() : Selects the range between two offsets..........................................................................................................120
EDI_SetPos() : Moves the insertion point to the specified offset............................................................................................120
EDI_StatusBar() : Reports line and column position on the Visual FoxPro statusbar.................................................................121
EDI_Undo() : Undoes the last action.................................................................................................................................121
EVENT FUNCTIONS..............................................................................................................................................................122
EVE_CustomizeEventCommand() : Customizes the command associated to a given event........................................................124
EVE_End() : Ends event processing...................................................................................................................................124
EVE_GetIdleSince() : Gets the last time when an event did occur that postponed the inactivity in a program..............................125
EVE_LastError() : Last error encountered in EVE functions...................................................................................................126
EVE_LastVersion() : Returns the file stamp of EVE functions.................................................................................................126
EVE_OnIdleCommand() : Gets/Sets the idle command........................................................................................................126
EVE_OnIdleInterval() : Gets/Sets the idle interval...............................................................................................................127
EVE_ResetIdleSince() : Resets the last event.....................................................................................................................128
EVE_SetUserDefinedAtNullCommand() : Sets a command to be launched at firts null event......................................................129
EVE_Start() : Starts event processing...............................................................................................................................130
FOCUS DATA FILE FUNCTIONS.............................................................................................................................................131

FDB_Append() : Appends a series of records to a FDB file....................................................................................................133
FDB_Create() : Creates a FDB file.....................................................................................................................................133
FDB_LastVersion() : Returns the file stamp of FDB functions................................................................................................133
FILE FUNCTIONS................................................................................................................................................................134
FIL_AreFileAPIsANSI() : Determines whether a set of Win32 file functions is using the ANSI or OEM character set code page.......137
FIL_BrowseForComputer() : Displays a dialog box that enables the user to select a computer...................................................137
FIL_BrowseForFolder() : Displays a dialog box that enables the user to select a shell folder.....................................................137
FIL_BrowseForPrinter() : Displays a dialog box that enables the user to select a printer...........................................................138
FIL_Canonicalize() : Canonicalizes a path..........................................................................................................................138
FIL_chdir() : Change Directory service..............................................................................................................................139
FIL_ClearArchived() : Clears the Archive attribute of a file....................................................................................................139
FIL_ClearCompressed() : Clears the Compressed attribute of a file........................................................................................139
FIL_ClearHidden() : Clears the Hidden attribute of a file......................................................................................................140
FIL_ClearNormal() : Clears the Normal attribute of a file......................................................................................................140
FIL_ClearReadOnly() : Clears the Read-Only attribute of a file..............................................................................................140
FIL_ClearSystem() : Clears the System attribute of a file.....................................................................................................140
FIL_ClearTmp() : Clears the Temporary attribute of a file.....................................................................................................141
FIL_close() : Closes a file................................................................................................................................................141
FIL_commit() : Flushes a file’s data buffer to disk...............................................................................................................141
FIL_Common() : Compares two paths to determine if they share a common prefix..................................................................142
FIL_comp() : Reports if two files are the same...................................................................................................................143
FIL_CompareTime() : Compares time and date stamps of two files.......................................................................................143
FIL_copy() : Copies a file................................................................................................................................................144
FIL_copyTimes() : Determines how many times the callback function of FIL_copy() will be called.............................................147
FIL_count() : Returns the number of files and directories that match a particular specification..................................................148
FIL_create() : Creates a file.............................................................................................................................................148
FIL_CreateHardLink() : Establishes an NTFS hard link between an existing file and a new file. An NTFS hard link is similar to a POSIX
hard link........................................................................................................................................................................150
FIL_crypt() : Encrypts a file.............................................................................................................................................151
FIL_decrypt() : Decrypts a file encrypted with FIL_crypt()....................................................................................................151
FIL_del() : Deletes file or directory...................................................................................................................................152
FIL_DeleteAll() : Deletes all file........................................................................................................................................152
FIL_drive() : Returns the drive letter from a complete path..................................................................................................153
FIL_exenam() : Returns the executable file name...............................................................................................................153
FIL_expand() : Expands a file...........................................................................................................................................154
FIL_Explore() : Explores a specified folder.........................................................................................................................154
FIL_ext() : Returns the three letter extension from a complete path......................................................................................155
FIL_first() : Gets first instance of a filename that matches a given file specification.................................................................155
FIL_FlushAll() : Flushes all streams; clears all buffers..........................................................................................................156
FIL_FndExe() : Find executable associated with a given filename..........................................................................................156
FIL_FullName() : Returns the full path to a specified file......................................................................................................156
FIL_gdate() : Gets file date stamp....................................................................................................................................157
FIL_get() : Open File Dialog Box.......................................................................................................................................157

Table Of Contents
FIL_getatt() : Gets file attribute........................................................................................................................................161
FIL_GetFolderLocation() : Obtains special folder location.....................................................................................................162
FIL_gets() : Gets a string from a file.................................................................................................................................163
FIL_GetStdin() : Reads a number of characters from the standard input (stdin)......................................................................164
FIL_GetTempFileName() : Creates a name for a temporary file.............................................................................................164
FIL_GetUniversalName() : Returns the Universal Name of a mapped resource........................................................................165
FIL_gtime() : Gets file time stamp....................................................................................................................................166
FIL_hleft() : Number of files that can still be open simultaneously.........................................................................................166
FIL_iatime() : Last access to file,......................................................................................................................................167
FIL_ImmediateCopy() : Copies a file.................................................................................................................................167
FIL_info() : Obtains general information about a file............................................................................................................167
FIL_IsArchived() : Is the given file an archived file?............................................................................................................168
FIL_isbof() : Is given file at BOF position?.........................................................................................................................168
FIL_IsCompressed() : Is the given file a compressed file?....................................................................................................169
FIL_IsDirectory() : Tests whether a file is marked with a directory flag..................................................................................169
FIL_isEOF() : Is given file at EOF position?........................................................................................................................169
FIL_IsFile() : Determines if the specified file exists..............................................................................................................170
FIL_IsHidden() : Is the given file hidden?..........................................................................................................................170
FIL_isize() : Gets file size................................................................................................................................................170
FIL_IsNormal() : Is the given file a normal file?..................................................................................................................171
FIL_IsReadOnly() : Is the given file read only?...................................................................................................................171
FIL_IsShared() : Is the given directory shared?..................................................................................................................171
FIL_IsShortcut() : Is a given file object a shortcut?.............................................................................................................172
FIL_IsSystem() : Is the given file a system file?.................................................................................................................172
FIL_IsTmp() : Is the given file a temporary file?.................................................................................................................172
FIL_isUNC() : Determines if the string is a valid UNC (universal naming convention) for a server and share path.........................172
FIL_LastVersion() : Returns the file stamp of FIL functions...................................................................................................173
FIL_len() : Determines the length of an open file................................................................................................................173
FIL_LenCompressed() : Obtains the compressed size, in bytes, of a specified file....................................................................174
FIL_mkdir() : Creates a directory......................................................................................................................................174
FIL_name() : Returns the file name from a complete path....................................................................................................175
FIL_next() : Gets next instance of a filename that matches a given file specification (see FIL_first()).........................................175
FIL_now() : Returns a file name in the YYYYMMDDHHmmSSXXXXXXXXXX format...................................................................175
FIL_open() : Opens a file in a given mode.........................................................................................................................176
FIL_OpenFile() : Attempts to open a file in SHARED mode. The file is closed upon exit of the function.......................................177
FIL_owner() : Finds the owner of a given file.....................................................................................................................177
FIL_path() : Returns the pathname from a complete path....................................................................................................178
FIL_puts() : Writes a string plus a carriage return line feed pair to a file.................................................................................178
FIL_PutStdout() : Outputs a string to the standard output device (stdout)..............................................................................179
FIL_read() : Returns a specified number of bytes................................................................................................................179
FIL_ReadAllSections() : Reads all the sections of any INI file................................................................................................180
FIL_ReadSub() : Reads a number of bytes from as specific location in a file...........................................................................180
FIL_ReadWININIAllSections() : Reads all the sections of the WIN.INI file...............................................................................181
FIL_reaini() : Reads a character string from an .INI file.......................................................................................................181
FIL_rename() : Renames a given file.................................................................................................................................181
FIL_rendir() : Renames a given file or directory..................................................................................................................182
FIL_rmdir() : Removes a directory....................................................................................................................................182
FIL_save() : Save File Dialog Box.....................................................................................................................................183
FIL_sdate() : Sets file date stamp.....................................................................................................................................184
FIL_sectio() : Reads .INI section......................................................................................................................................184
FIL_seek() : Moves the file pointer to a new position...........................................................................................................185
FIL_SetArchived() : Sets the Archive attribute of a file.........................................................................................................186
FIL_setatt() : Sets file attribute........................................................................................................................................186
FIL_SetCompressed() : Sets the Compressed attribute of a file.............................................................................................186
FIL_sethan() : Allocates file handles to the current process..................................................................................................187
FIL_SetHidden() : Sets the Hidden attribute of a file...........................................................................................................187
FIL_SetNormal() : Sets the Normal attribute of a file...........................................................................................................188
FIL_SetCompression() : Compresses a file.........................................................................................................................188
FIL_SetOpenStrategy() : Determines how the low-level functions of FOCUS will access files.....................................................188
FIL_SetReadOnly() : Sets the Read-Only attribute of a file...................................................................................................189
FIL_SetSystem() : Sets the System attribute of a file..........................................................................................................189
FIL_SetTmp() : Sets the Temporary attribute of a file..........................................................................................................190
FIL_ShortName() : Obtains the short name equivalent of a filename.....................................................................................190
FIL_size() : Determines the length of a file.........................................................................................................................190
FIL_slices() : Cuts a file into several slices of a given size....................................................................................................191
FIL_split() : Splits full filename into their basic components.................................................................................................191
FIL_stime() : Sets file time stamp.....................................................................................................................................192
FIL_StringToFile() : Writes a string to a file........................................................................................................................192
FIL_tell() : Determines the current location of a file pointer..................................................................................................193
FIL_tree() : Returns a tree of directories............................................................................................................................194
FIL_type() : Returns the type of the specified file................................................................................................................194
FIL_unzip() : Decompresses a file.....................................................................................................................................195
FIL_where() : Searches for the target file in a set of directories............................................................................................195
FIL_wipe() : File wiping...................................................................................................................................................196
FIL_wreain() : Reads a character string from WIN.INI file....................................................................................................196
FIL_wriini() : Copies a character string into a .INI file..........................................................................................................197
FIL_write() : Writes a character string to a file....................................................................................................................197
FIL_wsecti() : Reads WIN.INI section................................................................................................................................198
FIL_wwriin() : Copies a character string into the WIN.INI file...............................................................................................198
FIL_zip() : Compresses a file............................................................................................................................................198
FIL_zipLastError() : Last error encountered while in FIL_zip()/FIL_unzip()..............................................................................199

Table Of Contents
FTP FUNCTIONS.................................................................................................................................................................200
FTP_CloseAllSessions() : Closes all active FTP sessions........................................................................................................203
FTP_CloseSession() : Closes a FTP session for a given site...................................................................................................203
FTP_CreateDirectory() : Creates a new directory on the FTP site...........................................................................................203
FTP_DeleteFile() : Deletes a file stored on the FTP site........................................................................................................204
FTP_GetCurrentDirectory() : Retrieves the current directory for the specified FTP session.........................................................204
FTP_GetFile() : Retrieves a file from the FTP site and stores it locally....................................................................................205
FTP_FindFirstFile() : Searches the specified directory of the given FTP session........................................................................205
FTP_FindNextFile() : Searches for additional files................................................................................................................205
FTP_HandlesCount() : Returns the maximum number of FTP handles....................................................................................206
FTP_LastError() : Last error encountered in FTP functions....................................................................................................206
FTP_LastVersion() : Returns the file stamp of FTP functions.................................................................................................207
FTP_MaxHandle() : Returns the highest possible FTP handle.................................................................................................207
FTP_MinHandle() : Returns the lowest possible FTP handle...................................................................................................208
FTP_OpenSession() : Opens an FTP session for a given site.................................................................................................208
FTP_PutFile() : Stores a file on the FTP site........................................................................................................................209
FTP_RemoveDirectory() : Removes the specified directory on the FTP site.............................................................................209
FTP_RenameFile() : Renames a file or directory stored on the FTP site..................................................................................209
FTP_SetCurrentDirectory() : Changes to a different working directory on the FTP site..............................................................210
GRAPHICAL/GDI FUNCTIONS...............................................................................................................................................211
GDI_CreateEllipticRegion() : Creates an elliptical region.......................................................................................................213
GDI_CreatePolygonalRegion() : Creates a region based on a polygon....................................................................................214
GDI_DeleteRegion() : Frees a region and all its associated internal GDI objects......................................................................217
GDI_CombineRegions() : Creates a rectangular region........................................................................................................218
GDI_CreateRectangleRegion() : Creates a rectangular region...............................................................................................220
GDI_Ellipse() : Draws an ellipse.......................................................................................................................................222
GDI_LastVersion() : Returns the file stamp of GDI functions. GRA_LastVersion() : Returns the file stamp of GRA functions...........223
GDI_Rectangle() : Draws a rectangle................................................................................................................................223
GDI_RoundRectangle() : Draws a round rectangle...............................................................................................................225
GDI_ScreenToClient() : Converts the screen coordinates of a specified point on the screen to client-area coordinates..................226
GDI_ClientToScreen () : Converts the client-area coordinates of a specified point to screen coordinates.....................................227
GDI_Arc() : Draws an elliptical arc....................................................................................................................................227
GDI_ArcTo() : Draws an elliptical arc................................................................................................................................228
GDI_CreateSolidBrush() : Creates a brush that has the specified hatch pattern and color.........................................................228
GDI_chord() : Draws a chord...........................................................................................................................................229
GDI_circle() : Draws a circle............................................................................................................................................230
GRA_line() : Draws a line................................................................................................................................................230
GDI_SetPixel() : Draws a pixel.........................................................................................................................................231
GRA_carve() : Draws a box with carving effect...................................................................................................................231
HTML/HTTP FUNCTIONS....................................................................................................................................................232
HTML_Decode() : decodes an HTML encoded string.............................................................................................................234
HTML_Encode() : applies HTML encoding to the specified text string.....................................................................................234
HTML_LastVersion() : Returns the file stamp of HTML functions............................................................................................235
HTTP_AttemptConnect() : Attempts to make a connection to the Internet..............................................................................235
HTTP_CanonicalizeURL() : Canonicalizes a URL, which includes converting unsafe characters and spaces into escape sequences.. .236
HTTP_CrackURL() : Cracks a URL into a domain and path....................................................................................................237
HTTP_CombineURL() : Combines a base and a relative URL into a single URL.........................................................................237
HTTP_DecodeQueryString() : Decodes the QUERY_STRING of a URL request..........................................................................238
HTTP_GetCodeText() : Returns a descriptive text corresponding to a given HTTP responde code...............................................238
HTTP_GetDefaultBrowser() : Returns the default browser application that will be invoked for *.htm files....................................239
HTTP_GetURL() : Retrieves URL as a string........................................................................................................................240
HTTP_GetURL2() : Retrieves URL as a string......................................................................................................................241
HTTP_InternetDial() : Initiates a connection to the Internet using a modem...........................................................................250
HTTP_IsURL() : Returns status information about a URL......................................................................................................251
HTTP_LastError() : Last error encountered in HTTP functions................................................................................................254
HTTP_LastGetURLTime() : Returns the time the last HTTP_GetURL() operation in milliseconds..................................................254
HTTP_LastVersion() : Returns the file stamp of HTTP functions.............................................................................................255
HTTP_PostURL() : Gets URL and posts information..............................................................................................................255
HTTP_SetCallback() : Gets/Sets a callback function for the HTTP_GetURL*() functions.............................................................256
HTTP_SetURLTimeout() : Gets/Sets the timeout value used in HTTP functions........................................................................256
HTTP_URLDecode() : Decodes a URL.................................................................................................................................257
HTTP_URLEncode() : Encodes a URL.................................................................................................................................257
INI FILE FUNCTIONS..........................................................................................................................................................259

GetPrivateProfileString() : Reads a character string from an .INI file......................................................................................261
GetPrivateProfileSection() : Reads .INI section...................................................................................................................261
GetProfileSection() : Reads WIN.INI section.......................................................................................................................261
GetProfileString() : Reads a character string from the WIN.INI file........................................................................................262
WritePrivateProfileString() : Copies a character string into a .INI file.....................................................................................262
WriteProfileString() : Copies a character string into the WIN.INI file......................................................................................263
IP FUNCTIONS...................................................................................................................................................................264
IP_GetAddress() : Returns the IP address of the PC.............................................................................................................265
IP_GetIP() : Returns the IP address corresponding to a giuven domain name.........................................................................265
IP_LastError() : Determines the last error that occurred within the IP_*() functions.................................................................265
IP_LastVersion() : Returns the file stamp of IP functions......................................................................................................266
IP_ping() : Pings to an IP address.....................................................................................................................................266

Table Of Contents
KEYBOARD FUNCTIONS........................................................................................................................................................267
KEY_CodePage() : Retrieves the OEM code-page identifier for the system..............................................................................268
KEY_fast() : Sets the keyboard tick speed to its max...........................................................................................................268
KEY_fmax() : Returns the number of function keys on the keyboard......................................................................................269
KEY_GetLayoutName() : Retrieves the name of the active keyboard layout............................................................................269
KEY_HookF12() : Captures the F12 key.............................................................................................................................269
KEY_HookF12Proc() : Customizes the command to be executed when the F12 key is pressed...................................................270
KEY_HookPrtScr() : Captures the PrintScreen key...............................................................................................................271
KEY_HookPrtScrProc() : Customizes the command to be executed when the PrintScreen key is pressed.....................................271
KEY_iscaps() : returns the current status of the CapsLock key..............................................................................................272
KEY_IsShift() : Determines whether a shift key (left or right) is down....................................................................................272
KEY_IsLShift() : Determines whether the left shift key is down.............................................................................................272
KEY_IsRShift() : Determines whether the right shift key is down...........................................................................................272
KEY_IsCtrl() : Determines whether a control key (left or right) is down..................................................................................273
KEY_IsLCtrl() : Determines whether the left control key is down...........................................................................................273
KEY_IsRCtrl() : Determines whether the right control key is down.........................................................................................273
KEY_IsAlt() : Determines whether a alt key (left or right) is down.........................................................................................274
KEY_IsLAlt() : Determines whether the left alt key is down..................................................................................................274
KEY_IsRAlt() : Determines whether the right altl key is down...............................................................................................274
KEY_isins() : Returns the current status of the Ins key........................................................................................................274
KEY_isnum() : Returns the current status of the NumLock key..............................................................................................275
KEY_IsScrl() : Returns the current status of the ScrollLock key.............................................................................................275
KEY_LastVersion() : Returns the file stamp of KEY functions.................................................................................................275
KEY_norm() : Sets the keyboard tick speed to its normal cruise............................................................................................276
KEY_SetCap() : Sets the current status of the CapsLock key.................................................................................................276
KEY_SetNum() : Sets the current status of the NumLock key...............................................................................................276
KEY_SetScr() : Sets the current status of the ScrollLock key................................................................................................276
KEY_slow() : Sets the keyboard tick speed to its slowest speed............................................................................................277
KEY_type() : Retrieves information about the current keyboard............................................................................................277
KEY_UnHookF12() : Releases the capture of the PrintScreen key..........................................................................................278
KEY_UnHookPrtScr() : Releases the capture of the PrintScreen key.......................................................................................278
KERNEL FUNCTIONS............................................................................................................................................................279
KNL_major() : Returns the major version number of KERNEL.DLL.........................................................................................281
KNL_minor() : Returns the minor version number of KERNEL.DLL.........................................................................................281
KNL_vers() : Returns the version number of KERNEL.DLL....................................................................................................281
LANGUAGE SETTING FUNCTIONS............................................................................................................................................282

LNG_LastVersion() : Returns the file stamp of LNG functions................................................................................................283
LNG_MakeLangID() : constructs a language ID from a primary language ID and a sublanguage ID............................................283
LNG_set() : Gets/sets the internal language code................................................................................................................285
LOCALE SETTINGS...............................................................................................................................................................287
LOC_EnumSystemLocales() : Enumerates the locales that are installed on a system................................................................288
LOC_GetLocaleSetting() : Returns a locale setting...............................................................................................................288
LOC_GetSystemLocales() : Gets the locales that were enumerated via the LOC_EnumSystemLocales() function..........................290
LOC_GetUserDefaultLanguage() : Retrieves the user default language identifier......................................................................290
LOC_GetUserPrimaryLanguage() : Extracts a primary language identifier from a language identifier...........................................291
LOC_GetUserSubLanguage() : Extracts a sublanguage identifier from a language identifier.......................................................292
LOC_LastVersion() : Returns the file stamp of LOC functions................................................................................................294
LOG FUNCTIONS.................................................................................................................................................................295
LOG_Append() : Appends a line of text to a log file.............................................................................................................297
LOG_Close() : Closes a log file.........................................................................................................................................297
LOG_FindFirstLog() : Finds the first available log handle......................................................................................................298
LOG_LastError() : Determines the last error that occurred within the LOG_*() functions...........................................................298
LOG_LastVersion() : Returns the file stamp of LOG functions................................................................................................299
LOG_Set() : Sets a log file...............................................................................................................................................299
LOG_Successful() : Returns the string that is used to declare that the last operation has been successfully executed...................300
LZH FUNCTIONS.................................................................................................................................................................301
LZH_encode() : Compresses a file using the LZH algorithm..................................................................................................302
LZH_decode() : Uncompresses a file using the LZH algorithm...............................................................................................302
MAPI FUNCTIONS..............................................................................................................................................................303
THE MESSAGING APPLICATION PROGRAM INTERFACE FOR C PROGRAMMERS......305
SIMPLE MAPI FUNCTIONS...................................................................................................................................................305
SIMPLE MAPI STRUCTURES..................................................................................................................................................305

MapiFileDesc..................................................................................................................................................................305
MapiMessage.................................................................................................................................................................305
MapiRecipDesc...............................................................................................................................................................306
SIMPLE MAPI C FUNCTIONS INSIGHT....................................................................................................................................306

Logon/logoff process.......................................................................................................................................................306

Table Of Contents
Sending a message : MAPISendMail()................................................................................................................................308
Sending a document : MAPISendDocuments()....................................................................................................................308
Reading a message : MAPIReadMail()................................................................................................................................309
Next message : MAPIFindNext().......................................................................................................................................311
BUILDING A KIND OF "MAPI .FLL" FOR FOXPRO.....................................................................................................................312

Loading the MAPI libraries...............................................................................................................................................312
Determining whether MAPI is available or not.....................................................................................................................314
MAPI_IsMAPI() : Determines whether MAPI is installed........................................................................................................316
MCI FUNCTIONS................................................................................................................................................................317
MCI_device() : Retrieves the device identifier corresponding to the name of an open device.....................................................318
MCI_error() : Gets last MCI command error string..............................................................................................................318
MCI_IsRiff() : Is a given file in the RIFF format?.................................................................................................................318
MCI_IsWave() : Is a given file in the WAVE format?............................................................................................................319
MCI_LastVersion() : Returns the file stamp of MCI functions.................................................................................................319
MCI_send() : Sends a command to MCI devices.................................................................................................................319
METRIC FUNCTIONS............................................................................................................................................................320
MET_CmToInch() : Cm to inches......................................................................................................................................321
MET_FeetToInch() : Feet to inches....................................................................................................................................321
MET_FeetToMeters() : Feet to meters................................................................................................................................321
MET_FeetToMile() : Feet to miles......................................................................................................................................322
MET_FeetToYard() : Feet to yards.....................................................................................................................................322
MET_InchToCm() : Inches to cm......................................................................................................................................322
MET_InchToFeet() : Inches to feet....................................................................................................................................323
MET_InchToMile() : Inches to miles..................................................................................................................................323
MET_InchToYard() : Inches to yards.................................................................................................................................323
MET_KmToMile() : Km to mile..........................................................................................................................................324
MET_LastVersion() : Returns the file stamp of MET functions................................................................................................324
MET_MetersToFeet() : Meters to feet.................................................................................................................................324
MET_MileToKm() : Miles to km.........................................................................................................................................325
MET_MileToFeet() : Miles to feet.......................................................................................................................................325
MET_MileToInch() : Miles to inches...................................................................................................................................325
MET_MileToYard() : Miles to yards....................................................................................................................................326
MET_MToYard() : Meters to yards.....................................................................................................................................326
MET_YardToFeet() : Yards to feet.....................................................................................................................................326
MET_YardToInch() : Yards to inches..................................................................................................................................327
MET_YardToM() : Yards to meters.....................................................................................................................................327
MET_YardToMile() : Yards to mile.....................................................................................................................................327
MISCELLANEOUS FUNCTIONS.................................................................................................................................................329
MIS_Aliases() : Returns all the aliases that are known for a specified FOCUS.FLL function........................................................330
MIS_AllFunctions() : Returns all the function and aliases that are known in FOCUS.FLL............................................................330
MIS_Argc() : Number of arguments that a specified function of FOCUS.FLL expects................................................................331
MIS_Argv() : Argument types that a specified function of FOCUS.FLL expects.........................................................................331
MIS_BodyMassIndex() : Calculates the body mass index.....................................................................................................332
MIS_credits() : Returns the credits of FOCUS.FLL...............................................................................................................332
MIS_DocVers() : Returns the version of the FOCUS documentation.......................................................................................333
MIS_Error() : Generates a Visual FoxPro error....................................................................................................................333
MIS_ErrorInfo() : Visual FoxPro error message associated with the error...............................................................................334
MIS_ExecFuncPtr() : Executes the code that is pointed to by the internal execution pointer......................................................334
MIS_false() : Always returns a logical .F............................................................................................................................335
MIS_FuncPtr() : Returns a function pointer to a specified function contained in FOCUS.FLL.......................................................335
MIS_GetCommonSlot() : Gets/Sets the contents of a shared memory slot.............................................................................336
MIS_GetFocusUsage() : Gets the usage count of FOCUS.FLL................................................................................................337
MIS_IsFunction() : Returns .T. if a specified function exists in FOCUS.FLL..............................................................................337
MIS_knlmajor() : Returns the major version number of KERNEL.DLL.....................................................................................338
MIS_knlminor() : Returns the minor version number of KERNEL.DLL.....................................................................................338
MIS_knlvers() : Returns the version number of KERNEL.DLL................................................................................................338
MIS_LastVersion() : Returns the file stamp of MIS functions.................................................................................................339
MIS_major() : Returns the major version number of FOCUS.FLL...........................................................................................339
MIS_minor() : Returns the minor version number of FOCUS.FLL...........................................................................................340
MIS_nothin() : Does not do anything !..............................................................................................................................340
MIS_OnlineDocVers() : Returns the version of the FOCUS online documentation.....................................................................341
MIS_OutputDebugString() : Sends a string to the debugger for the current application............................................................341
MIS_NumberOfFunctions() : Number of functions included in FOCUS.FLL...............................................................................342
MIS_SetExecPtr() : Assigns the internal execution pointer to a given value.............................................................................342
MIS_true() : Always returns a logical .T.............................................................................................................................343
MIS_vers() : returns the version number of FOCUS.FLL.......................................................................................................343
MENU FUNCTIONS...............................................................................................................................................................345
MNU_AddItem() : Adds an item to a menu created with MNU_Make()....................................................................................346
MNU_AddMenu() : Attach a submenu to a menu.................................................................................................................348
MNU_create() : Creates a context menu at the position of the mouse....................................................................................350
MNU_Destroy() : Destroys an internal menu structure created with MNU_Make()....................................................................351
MNU_Make() : Creates an internal menu structure suitable for context menus........................................................................353
MNU_Play() : Plays a menu created by MNU_Make()...........................................................................................................355

Table Of Contents
MOUSE FUNCTIONS.............................................................................................................................................................358
MOU_ClipCursor() : Restricts the cursor to the specified area...............................................................................................359
MOU_FreeClipCursor() : Clears a previously set cursor clipping region...................................................................................362
MOU_isdown() : Is the left mouse button down?.................................................................................................................362
MOU_isLeftMouseDown() : Is the left mouse button down?..................................................................................................363
MOU_isLeftMouseUp() : Is the left mouse button up?..........................................................................................................363
MOU_isMiddleMouseDown() : Is the middle mouse button down?..........................................................................................363
MOU_isMiddleMouseUp() : Is the middle mouse button up?..................................................................................................364
MOU_isRightMouseDown() : Is the right mouse button down?..............................................................................................364
MOU_isRightMouseUp() : Is the right mouse button up?......................................................................................................364
MOU_LastVersion() : Returns the file stamp of MOU functions..............................................................................................365
MOU_LeftDown() : Simulates a left button down.................................................................................................................365
MOU_LeftUp() : Simulates a left button up.........................................................................................................................365
MOU_MiddleDown() : Simulates a middle button down........................................................................................................366
MOU_MiddleUp() : Simulates a middle button up................................................................................................................366
MOU_RightDown() : Simulates a right button down.............................................................................................................366
MOU_RightUp() : Simulates a right button up.....................................................................................................................367
MOU_Swap() : Swap mouse buttons.................................................................................................................................367
MQSERIES FUNCTIONS........................................................................................................................................................368
MQ_close() : Closes the current queue..............................................................................................................................371
MQ_connect() : Connects to the Queue Manager.................................................................................................................371
MQ_disconnect() : Disconnects from the Queue Manager.....................................................................................................371
MQ_open() : Opens a Queue............................................................................................................................................372
MESSAGING FUNCTIONS.......................................................................................................................................................373
MSG_Broadcast() : Sends a message to all recipients of the Post Office.................................................................................377
MSG_BytesSent() : Total number of bytes sent with the current Post Office............................................................................377
MSG_count() : Counts the number of unread messages for a given recipient..........................................................................377
MSG_CreateAccount() : Creates an account in the current Post Office....................................................................................378
MSG_CreatePostOffice() : Creates a Post Office..................................................................................................................378
MSG_DeleteAccount() : Deletes an account in the current Post Office....................................................................................379
MSG_DeleteUnread() : Deletes all pending messages of an account.......................................................................................379
MSG_GetAllAccounts() : Gets all accounts that are defined in the current Post Office...............................................................379
MSG_GetDir() : Returns the mailbox directory of a given recipient (absolute path)..................................................................380
MSG_GetSep() : Returns the separator that is used internally by FOCUS.FLL to tokenize a message..........................................381
MSG_GetSubDir() : Returns the mailbox directory of a given recipient (relative path)..............................................................381
MSG_IsAccount() : Determines if the specified account is known bt the current Post Office.......................................................382
MSG_IsPostOfficeAccessible() : Determines whether the Post Office can be contacted or not....................................................382
MSG_LastError() : Returns a string indicating the last error in Messaging functions..................................................................383
MSG_LastVersion() : Returns the file stamp of MSG functions...............................................................................................383
MSG_MessagesRead() : Returns the number of messages the specified recipient has already read.............................................384
MSG_MessagesReceived() : Returns the number of messages the specified recipient has received in total..................................384
MSG_MessagesSent() : Returns the number of messages a specified originator has sent..........................................................384
MSG_PO() : Gets the Post Office location...........................................................................................................................385
MSG_POFile() : Gets the Post Office settings file.................................................................................................................385
MSG_PostOffice() : Gets/Sets the Post office location and settings file...................................................................................385
MSG_Read() : Reads the least recent message of a given recipient.......................................................................................386
MSG_Send() : Sends a message.......................................................................................................................................386
MSG_SetPONotification() : Sets a directory notification on a specified directory......................................................................387
MSG_Successful() : Returns the string that is used to declare that the last operation has been successfully executed...................387
MSG_TotalMessagesSent() : Returns the total number of messages sent through the current Post Office....................................388
MATHEMATICAL FUNCTIONS..................................................................................................................................................389
MTH_atan() : Returns a Double specifying the arctangent of a number..................................................................................390
MTH_combinations() : Computes the number of unordered combinations of n on x.................................................................390
MTH_distance() : computes the distance between 2 points...................................................................................................392
MTH_LastVersion() : Returns the file stamp of MTH functions...............................................................................................392
MTH_origin() : détermine l'origine à l'ordonnée d'une droite passant par deux points..............................................................393
MTH_pente() : détermine la pente d'une droite passant par deux points................................................................................393
MTH_permutations() : Computes the number of ordered permutations of n on x.....................................................................394
NETWORK FUNCTIONS.........................................................................................................................................................395
NET_CancelConnection() : Breaks an existing network connection.........................................................................................396
NET_ConnectionDialog() : Presents a dialog box to establish a new network connection...........................................................396
NET_DisconnectDialog() : Presents a dialog box to cancel a network connection.....................................................................397
NET_EnumConnections() : Enumerates the network connections...........................................................................................398
NET_EthernetAddress() : Obtains the Ethernet address of the network card...........................................................................398
NET_GetComputerName() : Retrieves the computer name of the current system....................................................................399
NET_GetHostName() : Returns the standard host name for the local machine.........................................................................399
NET_GetUserName() : Returns the user name attached to the local machine..........................................................................399
NET_InternetTime() : Returns the Atomic clock date/time with 1sec accuracy.........................................................................400
NET_LastError() : Last error encountered in NET functions...................................................................................................400
NET_LastVersion() : Returns the file stamp of NET functions................................................................................................401
NET_level() : Sets up the user level..................................................................................................................................401
NET_max() : Maximum number of software users that can log in simultaneously....................................................................401
NET_mode() :?????????..................................................................................................................................................402
NET_proc() : Customizes the command to be executed by dedicated network timer................................................................402
NET_SetComputerName() : Sets the computer name to be used the next time the system is restarted......................................402
NET_setnet() : Must the network be setting up...................................................................................................................403

Table Of Contents
NET_timset() : Sets a timer dedicated to network attention..................................................................................................403
NET_timkil() : Kills the dedicated network timer.................................................................................................................404
NET_timkil() : Kills the dedicated network timer.NET_userno() : User number........................................................................404
NOTIFICATION FUNCTIONS...................................................................................................................................................405
NOT_Frequency() : Adjusts the frequency of the internal timer of FOCUS.FLL.........................................................................407
NOT_HandlesCount() : Returns the maximum number of notification handles.........................................................................407
NOT_HandlesFree() : Returns the number of free notification handles....................................................................................407
NOT_info() : Returns notification information.....................................................................................................................408
NOT_IsTimer() : Is the internal timer of FOCUS.FLL active?.................................................................................................409
NOT_Kill() : Kills a notification.........................................................................................................................................409
NOT_KillTimer() : Kills the internal timer of FOCUS.FLL.......................................................................................................410
NOT_LastError() : Returns an error string indicating the nature of the last error encountered....................................................410
NOT_LastVersion() : Returns the file stamp of NOT functions...............................................................................................411
NOT_MaxHandle() : Returns the highest possible notification handle.....................................................................................411
NOT_MinHandle() : Returns the lowest possible notification handle.......................................................................................411
NOT_RestoreAll() : Restores all notifications saved with NOT_SaveAll().................................................................................412
NOT_Resume() : Resumes a notification............................................................................................................................412
NOT_ResumeAll() : Resumes all notifications.....................................................................................................................413
NOT_SaveAll() : Saves all notifications in a character string.................................................................................................413
NOT_Set() : Sets a notification.........................................................................................................................................414
NOT_Strategy() : Establishes the strategy used to respond to directory notification.................................................................415
NOT_Successful() : Returns the string that is used to declare that the last operation has been successfully executed...................415
NOT_Suspend() : Suspends a notification..........................................................................................................................415
NOT_SuspendAll() : Suspends all notifications....................................................................................................................416
NOT_ZapAll() : Discards all notifications............................................................................................................................417
NTEVENTS FUNCTIONS........................................................................................................................................................418
NTE_ClearEventLog() : Clears a given event log.................................................................................................................421
NTE_CloseEventLog() : Closes a read handle to the specified event log..................................................................................421
NTE_OpenEventLog() : Opens an event log........................................................................................................................422
NUMERIC FUNCTIONS..........................................................................................................................................................423
NUM_Base() : Converts the digits of a given integer argument to a string, by taking into account a given radix...........................424
NUM_between() : Determines if a number is between 2 others.............................................................................................424
NUM_BinHi() : Returns the high byte value of a number......................................................................................................424
NUM_BinLow() : Returns the low byte value of a number.....................................................................................................425
NUM_gcd() : Euclid's implementation of the greatest common divisor of two integers..............................................................425
NUM_GetNextPrime() : Get the next prime number.............................................................................................................426
NUM_GetPrevPrime() : Get the previous prime number........................................................................................................426
NUM_hexa() : Hexadecimal equivalent of an integer............................................................................................................427
NUM_htoi() : Integer equivalent of an hexadecimal number.................................................................................................427
NUM_InitRandom() : Initializes internal buffers and values for random numbers generation.....................................................427
NUM_int_max() : Get the highest value of an integer..........................................................................................................428
NUM_int_min() : Get the lowest value of an integer............................................................................................................428
NUM_IsPrime() : Is a number a prime number?..................................................................................................................429
NUM_LastVersion() : Returns the file stamp of NUM functions...............................................................................................429
NUM_long_max() : Get the highest value of a long.............................................................................................................429
NUM_long_min() : Get the lowest value of a long...............................................................................................................430
NUM_octal() : Octal equivalent to an integer number..........................................................................................................430
NUM_Radix() : Reverse function of NUM_Base().................................................................................................................431
NUM_RandomDouble() : Generates a random float in the range 0 to 1...................................................................................431
NUM_RandomInt() : Generates a random integer................................................................................................................432
NUM_UniversalID() : Generates a unique identifier that is supposed to be unique in space and unique in time.............................432
OBJECT ORIENTED FUNCTIONS..............................................................................................................................................434

OBJ_AddProperty() : Adds a property to an object at Run-Time............................................................................................435
OBJ_LastVersion() : Returns the file stamp of OBJ functions.................................................................................................435
PRINTER FUNCTIONS...........................................................................................................................................................436
PRN_color() : Color printer to render color or monochrome output........................................................................................439
PRN_copies() : Number of copies printed if the device supports multiple-page copies..............................................................439
PRN_device() : Device name............................................................................................................................................439
PRN_dialog() : Displays a dialog box to setup application printer..........................................................................................440
PRN_driver() : Printer driver version number......................................................................................................................440
PRN_drv() : Printer driver name.......................................................................................................................................440
PRN_duplex() : Double-sided printing................................................................................................................................441
PRN_EnumPrinters() : Enumerates available printers...........................................................................................................441
PRN_extra() : Size of the optional dmDriverData member for device-specific data...................................................................442
PRN_fields() : Set of flags that indicate which members of the DEVMODE structure have been initialized....................................442
PRN_GetDefaultPrinter() : Gets the default printer...............................................................................................................443
PRN_GetDrvInfo() : Retrieves driver data for the specified printer.........................................................................................443
PRN_GetJobs() : List all printing jobs for a given printer......................................................................................................445
PRN_GetPrnData() : Retrieves information about a specified printer......................................................................................446
PRN_LastVersion() : Returns the file stamp of PRN functions................................................................................................451
PRN_name() : Device name/printer name..........................................................................................................................451
PRN_orient() : Paper orientation.......................................................................................................................................452
PRN_paperL() : Paper length, in tenths of a millimeter.........................................................................................................452
PRN_paperS() : Paper size...............................................................................................................................................452
PRN_paperW() : Paper width, in tenths of a millimeter........................................................................................................453

Table Of Contents
PRN_port() : Port connection...........................................................................................................................................454
PRN_qualit() : Printer resolution.......................................................................................................................................454
PRN_resolu() : Printer resolution (y-resolution)..................................................................................................................455
PRN_scale() : Factor by which the printed output is to be scaled...........................................................................................455
PRN_SetDefaultPrinter() : Sets the default printer...............................................................................................................456
PRN_SetPrnData() : Sets information in a given printer.......................................................................................................456
PRN_size() : Size of the DEVMODE structure......................................................................................................................460
PRN_source() : Default bin from which the paper is fed.......................................................................................................460
PRN_spec() : Version number of the DEVMODE structure.....................................................................................................461
PRN_TTopt() : How should TrueType fonts be printed?........................................................................................................461
REGISTRY FUNCTIONS.........................................................................................................................................................462
REG_CreateKey() : Creates a key in the Windows registry....................................................................................................463
REG_CreateValue() : Creates a value in the Windows registry...............................................................................................463
REG_DeleteKey() : Deletes a key in the Windows registry....................................................................................................464
REG_DeleteValue() : Deletes a value in the Windows registry...............................................................................................464
REG_EnumKeyEx() : Enumerates all subkeys of a given key of the Windows registry...............................................................465
REG_LastVersion() : Returns the file stamp of REG functions................................................................................................465
REG_QueryValue() : Gets data from the Registry................................................................................................................466
REGULAR EXPRESSIONS FUNCTIONS.......................................................................................................................................467

RG_Compile() : Compiles a pattern that will be used in subsequent calls to RG_Execute()........................................................471
RG_Execute() : Performs a regular expression search..........................................................................................................471
RG_Match() : match of the whole last regular expression.....................................................................................................471
SCREEN FUNCTIONS............................................................................................................................................................473
SCR_BitmapHeight() : Height of bitmaps contained in title bar.............................................................................................474
SCR_BitmapWidth() : Width of bitmaps contained in title bar...............................................................................................474
SCR_ColorDepth() : Determines screen color depth.............................................................................................................474
SCR_cols() : Displays width in pixels.................................................................................................................................475
SCR_EnumDisplaySettings() : Retrieves information about one of the graphics modes for a display device.................................475
SCR_GetDMMember() : Retrieves a member of the internal DEVMODE structure that is populated after a call to
SCR_EnumDisplaySettings()............................................................................................................................................476
SCR_GetFullScreenDimensions() : Determines the usable dimensions of the Windows desktop.................................................477
SCR_GetScreenDimensions() : Determines the usable dimensions of the Windows desktop......................................................477
SCR_LastVersion() : Returns the file stamp of SCR functions................................................................................................478
SCR_MinimumDragHeight() : Minimum tracking height of a window......................................................................................478
SCR_MinimumDragWidth() : Minimum tracking width of a window........................................................................................478
SCR_RefreshDisplay() : Refreshes the entire display...........................................................................................................479
SCR_ResetDisplaySettings() : Returns to the default mode display........................................................................................479
SCR_roloc() : Reverses color attribute...............................................................................................................................480
SHELL FUNCTIONS..............................................................................................................................................................481
SHE_AddIcon() : Adds an icon in the System Tray of Windows.............................................................................................483
SHE_CopyFile() : Copies multiple source files from one location to another............................................................................484
SHE_DeleteAllTrayIcons() : Removes all icons set with SHE_AddIcon().................................................................................485
SHE_DeleteIcon() : Removes an icon from the System Tray of Windows................................................................................486
SHE_GetDllVersion() : Obtains version information from the shell32.dll.................................................................................487
SHE_GetIconCount() : Get the number of icons found in an executable, or .DLL.....................................................................487
SHE_IconsFree() : Determines how many icons can still be placed in the System Tray of Windows............................................488
SHE_IsActiveDesktopInstalled() : Checks for the Active Desktop...........................................................................................488
SHE_LastError() : Returns the last error that occurred in the SHE_*() functions......................................................................489
SHE_LastVersion() : Returns the file stamp of SHE functions................................................................................................489
SHE_QueryRecycleBin() : Determines the number of deleted items in the recycle bin of a specific drive.....................................489
SHE_PathAddBackslash() : Adds a backslash to the end of a path.........................................................................................490
SHE_PathCompact() : Truncates a path to fit within a certain number of characters by replacing path components with ellipses....490
SHE_PathIsRelative() : Searches a path and determines if it is relative..................................................................................491
SHE_PathIsRoot() : Parses a path to determine if it is a directory root...................................................................................491
SHE_PathIsUNC() : Determines if the string is a valid UNC (universal naming convention) for a server and share path.................492
SHE_PathIsUNCServer() : Determines if a string is a valid UNC for a server path only..............................................................492
SHE_PathIsUNCServerShare() : Determines if a string is a valid UNC share path, \\server\share...............................................492
SHE_PathIsURL() : Tests a given string to determine if it conforms to a valid URL format.........................................................493
SHE_PathRemoveBackslash() : Removes the trailing backslash from a given path...................................................................493
SIZEOF FUNCTIONS.............................................................................................................................................................494
SIZ_bool() : Size of a bool..............................................................................................................................................495
SIZ_char() : Size of a char..............................................................................................................................................495
SIZ_double() : Size of a double........................................................................................................................................495
SIZ_dword() : Size of a DWORD.......................................................................................................................................495
SIZ_enum() : Size of an enum.........................................................................................................................................496
SIZ_float() : Size of a float..............................................................................................................................................496
SIZ_int() : Size of an integer...........................................................................................................................................496
SIZ_int8() : Size of a 8-bit integer....................................................................................................................................496
SIZ_int16() : Size of a 16-bit integer................................................................................................................................497
SIZ_handle() : Size of a handle........................................................................................................................................497
SIZ_hwnd() : Size of a window handle (HWND).................................................................................................................498
SIZ_LastVersion() : Returns the file stamp of the SIZ functions............................................................................................498
SIZ_long() : Size of a long..............................................................................................................................................498

Table Of Contents
SIZ_longdouble() : Size of a long double...........................................................................................................................498
SIZ_short() : Size of a short............................................................................................................................................499
SIZ_tchar() : Size of a TCHAR..........................................................................................................................................499
SIZ_uint() : Size of an unsigned integer............................................................................................................................499
SIZ_wchar() : Size of a WCHAR.......................................................................................................................................499
SIZ_whandle() : Size of a window handle (WHANDLE)........................................................................................................500
SOUND FUNCTIONS.............................................................................................................................................................501
SND_AppEvent() : Plays a waveform identified by an entry in the registry..............................................................................502
SND_asterisk() : Plays a waveform identified by an entry in the registry (iconasterisk)............................................................502
SND_error() : Plays a waveform identified by an entry in the registry (iconhand)....................................................................503
SND_exclamation() : Plays a waveform identified by an entry in the registry (iconexclamation)................................................503
SND_LastVersion() : Returns the file stamp of SND functions...............................................................................................503
SND_OK() : Plays a waveform identified by an entry in the registry (iconok)..........................................................................504
SND_play() : Plays a waveform sound specified by a filename..............................................................................................504
SND_repeat() : Repeats the last waveform that was played.................................................................................................504
SND_Standard() : Standard beep using the computer speaker..............................................................................................505
SND_Stop() : Stops playing any wave file..........................................................................................................................505
SND_vers() : Returns the FOCUS Sound version.................................................................................................................505
SYSTEM PARAMETERS INFO FUNCTIONS..................................................................................................................................506

SPI_GetBeep() : Determines whether the warning beeper is on............................................................................................510
SPI_GetBorder() : Retrieves the border multiplier factor that determines the width of a window's sizing border...........................510
SPI_GetDoubleClickHeight() : Height in pixels of the double-click rectangle............................................................................510
SPI_GetDoubleClickTime() : Retrieves the current double-click time for the mouse..................................................................511
SPI_GetDoubleClickWidth() : Width in pixels of the double-click rectangle..............................................................................511
SPI_GetFastTaskSwitch() : Is Alt-Tab enabled?..................................................................................................................511
SPI_GetGrid() : Retrieves the current granularity value of the desktop sizing grid....................................................................512
SPI_GetIconTitleWrap() : Determines whether icon-title wrapping is enabled..........................................................................512
SPI_GetKeyboardDelay() : Retrieves the keyboard repeat-delay setting.................................................................................512
SPI_GetKeyboardSpeed() : Retrieves the keyboard repeat-speed setting...............................................................................513
SPI_GetLastError() : Returns the last error encountered when using SPI_*() functions.............................................................513
SPI_GetMenuDropAlignment() : Determines whether pop-up menus are left-aligned or right-aligned, relative to the corresponding
menu-bar item...............................................................................................................................................................513
SPI_GetScreenReader() : Determines whether a screen reviewer utility is running...................................................................514
SPI_GetScreenSaveActive() : Determines whether screen saving is enabled...........................................................................514
SPI_GetScreenSaveTimeout() : Gets the screen saver time-out value....................................................................................514
SPI_GetShowSounds() : Determines whether the Show Sounds accessibility flag is on or off....................................................515
SPI_GetWorkArea() : Retrieves the size of the working area.................................................................................................515
SPI_LastVersion() : Returns the file stamp of SPI functions..................................................................................................516
SPI_SetBorder() : Sets the border multiplier factor that determines the width of a window's sizing border..................................516
SPI_SetBeep() : Turns the warning beeper on or off............................................................................................................517
SPI_SetDoubleClickHeight() : Height in pixels of the double-click rectangle............................................................................517
SPI_GetDoubleClickTime() : Sets the current double-click time for the mouse........................................................................517
SPI_SetDoubleClickWidth() : Width in pixels of the double-click rectangle..............................................................................518
SPI_SetFastTaskSwitch() : Enables or disables Alt-Tab........................................................................................................518
SPI_SetGrid() : Sets the granularity of the desktop sizing grid..............................................................................................518
SPI_SetIconHorizontalSpacing() : Sets the width of an icon cell............................................................................................519
SPI_SetIconTitleWrap() : Enables or disables icon-title wrapping..........................................................................................519
SPI_SetIconVeriticalSpacing() : Sets the height of an icon cell..............................................................................................519
SPI_SetKeyboardDelay() : Sets the keyboard repeat-delay setting........................................................................................519
SPI_SetKeyboardSpeed() : Sets the keyboard repeat-speed setting......................................................................................520
SPI_SetMenuDropAlignment() : Sets the alignment value of pop-up menus............................................................................520
SPI_SetMouseButtonSwap() : Swaps or restores the meaning of the left and right mouse buttons.............................................521
SPI_SetScreenSaveActive() : Sets the state of the screen saver............................................................................................521
SPI_SetScreenSaveTimeout() : Sets the screen saver time-out value....................................................................................521
SPI_SetWallpaper() : Sets the Windows wallpaper..............................................................................................................521
SPI_SetWorkArea() : Retrieves the size of the working area.................................................................................................522
SPI_Successful() : Returns the string that is used to declare that the last operation has been successfully executed....................522
STRING FUNCTIONS............................................................................................................................................................523
STR_addcod() : Adds an ASCII code to each character of a string.........................................................................................524
STR_AllChars() : Returns all the characters found in a string in a sorted manner.....................................................................524
STR_ascii() : Forms a number based on each character value...............................................................................................524
STR_ascii2() : Forms a number based on each character value multiplied by its position..........................................................525
STR_Ascii2Ebcdic() : Converts a string to its EBCDIC equivalent...........................................................................................525
STR_AtLine() : Determines the number of the line a given position belongs to........................................................................526
STR_balanc() : Finds position where a given character is balanced with another.....................................................................527
STR_char() : Extracts the rest of a string...........................................................................................................................528
STR_chrcnt() : Counts occurrences of a character in a string................................................................................................528
STR_chrswa() : Swaps one character with another within a string.........................................................................................529
STR_comma() : Formats a string that only contains digits....................................................................................................529
STR_CompareStrings() : Compares two character strings, using the current User Locale as the basis for the comparison.............529
STR_Compare() : Compares two character strings, and reports where they differ....................................................................530
STR_ConvertA2B() : Converts a character string based on an internal conversion table............................................................531
STR_ConvertB2A() : Reverses the conversion set by the STR_ConvertA2B() function..............................................................531
STR_cpbrk() : Finds the 1st occurrence in a string of any character from another string. String result........................................532
STR_Decode64() : Decodes a base 64 encoded string.........................................................................................................533
STR_dionly() : Keeps digits only.......................................................................................................................................533
STR_Ebcdic2Ascii() : Converts a string to its ASCII equivalent..............................................................................................533
STR_Encode64() : Encodes a string in base 64...................................................................................................................534

Table Of Contents
STR_encrypt() : Encrypts a string.....................................................................................................................................534
STR_end() : Does a string end with a given value?..............................................................................................................535
STR_exclude() : Excludes characters that are in a string......................................................................................................535
STR_find() : Finds an occurrence of a substring in a string (two times faster than AT())...........................................................536
STR_FindBackward() : Finds an occurrence of a substring in a string (two times faster than RAT()) starting from the end of the
string............................................................................................................................................................................536
STR_first() : Finds the first character that is not a space......................................................................................................537
STR_FormatByteSize() : Converts a numeric value into a string that represents the number expressed as a size value in bytes,
kilobytes, megabytes, or gigabytes, depending on the size..................................................................................................537
STR_getoff() : Gets the internal offset position...................................................................................................................538
STR_GeneratePassword() : Generates a random password...................................................................................................538
STR_hexa() : Hexadecimal equivalent of a string................................................................................................................539
STR_htos() : Original string corresponding to an hexadecimal string.....................................................................................539
STR_IsAlpha() : Determines if a given string contains only alpha characters...........................................................................540
STR_IsAlphaNumeric() : Determines if a given string contains only alphanumeric characters....................................................540
STR_IsPunct() : Determines if a given string contains only punctuation marks........................................................................541
STR_IsSpace() : Determines if a given string contains only spaces........................................................................................541
STR_IsGraph() : Determines if a given string contains only graph characters..........................................................................542
STR_IsPrint() : Determines if a given string contains only graph characters............................................................................542
STR_IsCharAlpha() : Determines if a given character is an alpha character.............................................................................543
STR_IsCharAlphaNumeric() : Determines if a given character is an alphanumeric character......................................................543
STR_IsCharDigit() : Is a given character a digit?.................................................................................................................544
STR_IsCharGraph() : Is a given character printable while not being a space?..........................................................................544
STR_IsCharLower() : Determines if a given character of a specified string is a lowercase character............................................545
STR_IsCharPrint() : Is a given character printable?.............................................................................................................545
STR_IsCharPunct() : Is a given character a punctuation character?.......................................................................................546
STR_IsCharSpace() : Is a given character a white space character?.......................................................................................546
STR_IsCharUpper() : Determines if a given character of a specified string is an uppercase character.........................................547
STR_IsCharXDigit() : Determines if a given character of the specified string is a hexadecimal digit............................................547
STR_IsDigit() : Determines if characters of the specified string are digits...............................................................................548
STR_IsDigitOrDecimalSeparator() : Determines if characters of the specified string are digits or decimal separator (".")...............548
STR_IsInSet() : Determines if characters of the specified string belongs to a set of characters..................................................549
STR_IsNumber() : Determines if a string forms a number....................................................................................................549
STR_IsLower() : Determines if characters of the specified string are lowercase characters........................................................550
STR_IsUpper() : Determines if characters of the specified string are uppercase characters.......................................................551
STR_IsValidCreditCard() : Determines whether a credit card number is correct or not..............................................................551
STR_IsXDigit() : Determines if characters of the specified string are hexadecimal digits...........................................................552
STR_keep() : Keeps specified characters from a string........................................................................................................552
STR_KeepConsonants() : Keeps the consonants of a string..................................................................................................552
STR_KeepVowels() : Keeps the vowels of a string...............................................................................................................553
STR_last() : Finds the last character that is not a space.......................................................................................................553
STR_LastVersion() : Returns the file stamp of STR functions................................................................................................553
STR_Left() : Returns a specified number of characters from a character expression, starting with the leftmost character..............554
STR_Length() : Determines the length of a string...............................................................................................................554
STR_Like() : Strings comparison with wildcards..................................................................................................................555
STR_LikeCase() : Indicates whether STR_Like() should be case sensitive or not (Get/Set function)...........................................557
STR_LikeGetToken() : Returns the last token specified when using STR_Like().......................................................................557
STR_ltrim() : Returns the specified character expression with leading blanks removed.............................................................558
STR_mirror() : Reverses a string......................................................................................................................................558
STR_MixUp() : Mix up a string..........................................................................................................................................559
STR_n() : Extracts the nth character of a string...................................................................................................................559
STR_nparam() : Extracts the nth parameter of a string.........................................................................................................560
STR_npbrk() : Finds the 1st occurrence in a string of any character from another string. Numeric result....................................560
STR_nset() : Set first n characters of string to specified character.........................................................................................561
STR_ntoken() : Extracts a given token from a string...........................................................................................................561
STR_null() : Returns a null string (empty string).................................................................................................................562
STR_numtok() : Determines the number of tokens in a string...............................................................................................562
STR_occu() : Determines position of nth occurrence of a character in a string..........................................................................563
STR_peek() : Returns the ASCII code of a given character in a string....................................................................................563
STR_poke() : Poke a character at given position in string.....................................................................................................564
STR_Proper() : Returns a string capitalized appropriately for proper names............................................................................564
STR_raw() : Forms a string of characters comprised between a given ASCII range..................................................................565
STR_reduce() : Reduces consecutive occurrences of the same character to only 1 occurrence...................................................565
STR_relin() : Run Encoding Length algorithm (In)...............................................................................................................566
STR_relout() : Run Encoding Length algorithm (Out)...........................................................................................................566
STR_Replace() : Replaces a substring with another in a string..............................................................................................566
STR_ResetLikeCharConversions() : Resets the conversion table for STR_Like().......................................................................567
STR_Right() : Returns a specified number of characters from a character expression, starting with the rightmost character..........567
STR_rtrim() : Returns the specified character expression with trailing blanks removed.............................................................568
STR_SetCharConversion() : Gets/sets a new character conversion for STR_ConvertA2B() and STR_ConvertB2A().......................568
STR_SetConvTable() : Sets a conversion table for STR_ConvertA2B() and STR_ConvertB2A()..................................................569
STR_SetLikeCharConversion() : Gets/sets a new character conversion for STR_Like().............................................................570
STR_setoff() : Sets the internal offset position of token functions.........................................................................................570
STR_setsep() : Gets/sets the internal separator for token based functions..............................................................................571
STR_shl() : Shifts-Left a string by a given number of bits....................................................................................................571
STR_shr() : Shifts-Right a string by a given number of bits..................................................................................................572
STR_sort() : Sorts all the characters in a string..................................................................................................................572
STR_soundex() : Returns a phonetic key reprsenting a name...............................................................................................572
STR_start() : Does a string start with a given value?...........................................................................................................573
STR_strip() : Strips characters in a given range from a character string.................................................................................573
STR_strtok() : Extracts a token from a string.....................................................................................................................574
STR_TillNull() : Returns a string up to the first null character................................................................................................574

Table Of Contents
STR_tokfin() : Did we process the entire string?.................................................................................................................574
STR_tokini() : Initializes internal counters for token processing............................................................................................575
STR_toknex() : Gets the next token..................................................................................................................................576
STR_tokpos() : Determines the starting position of a given token.........................................................................................577
STR_TrimLeft() : Trims off x characters from the left of a string............................................................................................577
STR_TrimRight() : Trims off x characters from the right of a string........................................................................................578
SYSTEM FUNCTIONS............................................................................................................................................................579
SYS_ACLineStatus() : AC power status..............................................................................................................................580
SYS_AllocConsole() : Allocates a new console to the current program (EXE)...........................................................................580
SYS_avaclu() : Gets the number of available clusters on disk...............................................................................................580
SYS_BatteryFlag() : Battery charge status.........................................................................................................................581
SYS_BatteryFullLifeTime() : Number of seconds of battery life when at full charge..................................................................581
SYS_BatteryLifePercent() : Percentage of full battery charge remaining.................................................................................582
SYS_BatteryLifeTime() : Number of seconds of battery life remaining....................................................................................582
SYS_Broadcast() : Broadcasts a WIN.INI change to all applications.......................................................................................582
SYS_bytsec() : Gets the number of bytes per sector on given disk........................................................................................583
SYS_ConfigurePort() : Displays the port-configuration dialog box for a port...........................................................................583
SYS_GetConsoleHWND() : Returns the Windows handle of the current console.......................................................................585
SYS_GetConsoleTitle() : Gets the title of the current console................................................................................................586
SYS_CreateMutex() : Creates a named mutex object...........................................................................................................586
SYS_curdri() : Obtains the current drive............................................................................................................................587
SYS_DeleteMutex() : Releases mutex object......................................................................................................................587
SYS_displa() : Returns the display driver which is used by Windows......................................................................................587
SYS_DoesDriveExist() : Finds out if given drive exists in the system.....................................................................................588
SYS_DoesSupportCompression() : Does the file system support file-based compression..........................................................588
SYS_dosmaj() : Returns DOS major version number...........................................................................................................588
SYS_dosmin() : Returns DOS minor version number...........................................................................................................589
SYS_dristr() : Returns a string with all drives.....................................................................................................................589
SYS_DriveType() : Returns the drive type..........................................................................................................................589
SYS_dsksiz() : Returns the total capacity in bytes of a specified disk drive.............................................................................590
SYS_dskspa() : Returns the number of available bytes on a given disk drive..........................................................................591
SYS_EnumDeviceDrivers() : List of active device drivers in the system..................................................................................592
SYS_errhan() : Custom Windows error handling.................................................................................................................593
SYS_exenam() : Returns the executable file name..............................................................................................................593
SYS_ExitProcess() : Ends a process and all of its threads.....................................................................................................594
SYS_ExitWindows() : Either logs off, shuts down, or shuts down and restarts the system........................................................594
SYS_FatalExit() : Displays a message box and terminates the application..............................................................................595
SYS_FileSystemName() : File system installed on a given drive............................................................................................595
SYS_FormatDrive() : Presents the standard dialog box of Windows to format a drive...............................................................596
SYS_FreeConsole() : Frees the current console (if any).......................................................................................................596
SYS_FreeLibrary() : Unloads a 32-bit DLL previously loaded with SYS_LoadLibrary()...............................................................597
SYS_GetBinaryType() : Determines the type of an executable..............................................................................................597
SYS_GetCaretBlinkTime() : Returns the elapsed time, in milliseconds, required to invert the caret's pixels.................................598
SYS_GetCaretPosX() : Caret's position, in client coordinates................................................................................................598
SYS_GetCaretPosY() : Caret's position, in client coordinates.................................................................................................599
SYS_GetCommandLine() : Command-line string for the current process................................................................................599
SYS_GetCurrentDirectory() : Returns current directory........................................................................................................599
SYS_GetDllVersion() : Obtains version information from any DLL..........................................................................................600
SYS_GetEnvironmentStrings() : Retrieves the whole environment block of the current process.................................................601
SYS_GetEnvironmentVariable() : Retrieves the value of the specified variable from the environment block of the calling process...601
SYS_GetHInstance() : Retrieves the handle of the application instance that handles the main FoxPro window.............................602
SYS_GetLocalTime() : Gets the local time..........................................................................................................................602
SYS_GetNumDrives() : Finds out how many drives exist in the system..................................................................................603
SYS_GetStdHandle() : Gets the handle of a standard handle................................................................................................603
SYS_GetSysColor() : Retrieves the current color of the specified display element....................................................................604
SYS_GetSystemMetrics() : Retrieves various system metrics and system configuration settings................................................605
SYS_GetThreadLocale() : Returns the calling thread's current locale......................................................................................607
SYS_GetTickCount() : Retrieves the number of milliseconds that have elapsed since Windows was started.................................608
SYS_GetTimeZoneInformation() : Retrieves the current time-zone parameters.......................................................................609
SYS_GetTmpPath() : Gets the Windows temporary path......................................................................................................610
SYS_GlobalMemoryStatus() : Retrieves information about current available memory...............................................................611
SYS_HideCaret() : Removes the caret from the screen........................................................................................................611
SYS_inp() : input a byte from a port.................................................................................................................................612
SYS_iscd() : Is the given drive a CD-ROM?........................................................................................................................612
SYS_IsCompressed() : Determines if the specified volume is a compressed volume................................................................613
SYS_isDMA() : Is a DMA installed.....................................................................................................................................613
SYS_IsDriveReady() : Is a given drive ready?.....................................................................................................................613
SYS_IsFileCaseSensitive() : Does the system distinct between upper and lower case filenames?...............................................614
SYS_IsFileCasePreserved() : Does the system preserve cases?.............................................................................................614
SYS_isfixe() : Is the given drive a fixed drive?....................................................................................................................615
SYS_IsFlop() : Is the given drive a floppy drive? (is disk removable?)...................................................................................615
SYS_IsGame() : Is a game adapter present?......................................................................................................................616
SYS_IsLoaded() : Determines if a process (EXE) or library (DLL) is loaded.............................................................................616
SYS_IsMath() : Is Math coprocessor present?.....................................................................................................................617
SYS_IsModem() : Is a modem present?.............................................................................................................................617
SYS_IsMutex() : Does a given mutex object exist...............................................................................................................617
SYS_isNT() : Is the application running under Windows NT?.................................................................................................618
SYS_ispen() : Is it a pen computing prepared machine?......................................................................................................618
SYS_isram() : Is the given drive a RAM disk?.....................................................................................................................619
SYS_isremo() : Is the given drive a remote drive?..............................................................................................................619

Table Of Contents
SYS_IsUnicodeOnDisk() : Does the file system support Unicode in filenames as they appear on disk?........................................620
SYS_IsValidLocale() : Validity test to a locale identifier........................................................................................................620
SYS_JoyStickCaps() : Determines if the capabilities of a joystick can be queried.....................................................................620
SYS_JoyStickEnumDevs() : Returns the number of joysticks the joystick driver supports.........................................................621
SYS_KillProcess() : Kills a given task.................................................................................................................................621
SYS_LastError() : Gets system functions last error..............................................................................................................622
SYS_LastVersion() : Returns the file stamp of SYS functions................................................................................................622
SYS_LoadLibrary() : Attempts to load a 32-bit DLL.............................................................................................................623
SYS_LookupDomain() : Returns the first domain on which a specified user is defined..............................................................623
SYS_MakeDrive() : From a number, it returns a drive letter.................................................................................................624
SYS_MaxApplAddress() : Returns the highest memory address accessible to applications and dynamic-link libraries (DLLs)..........624
SYS_MaxFileLength() : Obtains maximum filename length for a given disk.............................................................................624
SYS_MediaType() : Determines the media type..................................................................................................................625
SYS_MinApplAddress() : Returns the lowest memory address accessible to applications and dynamic-link libraries (DLLs)............625
SYS_MinimumDragHeight() : Minimum tracking height of a window......................................................................................625
SYS_MinimumDragWidth() : Minimum tracking width of a window........................................................................................626
SYS_ModuleHandle() : Returns a module handle for a specified module.................................................................................626
SYS_ModuleName() : Retrieves the full path and filename for the executable file containing the specified module.......................627
SYS_mouse() : Returns the mouse driver which is used by Windows.....................................................................................628
SYS_networ() : Returns the network driver which is used by Windows..................................................................................628
SYS_numflo() : Floppy disk count.....................................................................................................................................628
SYS_numprn() : Number of printers..................................................................................................................................629
SYS_os() : Get OS infos..................................................................................................................................................629
SYS_OSLastError() : Returns an error string from the Operating System about the last operation.............................................630
SYS_outp() : output a byte to a port.................................................................................................................................630
SYS_P3Serial() : Pentium III serial number........................................................................................................................630
SYS_PageSize() : Specifies the page size and the granularity of page protection and commitment.............................................631
SYS_Processes() : List of active tasks in the system............................................................................................................631
SYS_ProcessesId() : List of IDs of all active tasks...............................................................................................................632
SYS_ProcessorArchitecture() : Specifies the system's processor architecture..........................................................................633
SYS_ProcessorMask() : Returns a mask representing the set of processors configured into the system......................................633
SYS_RealExecutableName() : Gets the name of the executable.............................................................................................634
SYS_RemoteShutdown() : Initiates a shutdown and optional restart of the specified computer.................................................634
SYS_secclu() : Gets the number of sectors per cluster on given disk.....................................................................................635
SYS_SendMessage() : Sends a specified message to a window (or windows).........................................................................636
SYS_SetCaretBlinkTime() : Sets the caret blink time to the specified number of milliseconds....................................................636
SYS_SetCaretPos() : Sets caret's position, in client coordinates............................................................................................637
SYS_SetConsoleTitle() : Sets the title of the current console................................................................................................637
SYS_setdri() : Sets current drive......................................................................................................................................638
SYS_SetEnvironmentVariable() : Sets the value of an environment variable for the current process...........................................638
SYS_SetErrorMode() : Controls whether the system will handle the specified types of serious errors, or whether the process will
handle them..................................................................................................................................................................639
SYS_SetFileAPIsToANSI() : Causes a set of Win32 file functions to use the ANSI character set code page..................................639
SYS_SetFileAPIsToOEM() : Causes a set of Win32 file functions to use the OEM character set code page....................................640
SYS_SetLocalTime() : Gets the local time..........................................................................................................................640
SYS_setvol() : Sets a new volume label for a given disk......................................................................................................641
SYS_ShellAbout() : Displays a Shell About dialog box.........................................................................................................641
SYS_ShellExecute() : Opens, explores or prints a specified file.............................................................................................642
SYS_ShellExecuteEx() : Opens, explores or prints a specified file..........................................................................................643
SYS_ShowCaret() : Makes the caret visible on the screen at the caret's current position..........................................................644
SYS_sleep() : Suspends the execution of the current thread for a specified interval.................................................................645
SYS_SplitTime() : Splits the current local time into its base components................................................................................645
SYS_StartService() : Starts a Windows NT Service.............................................................................................................646
SYS_StopService() : Stops a Windows NT Service..............................................................................................................647
SYS_swap() : Returns the name of the Windows swap file...................................................................................................647
SYS_sysdir() : Obtains the pathname of the Windows system directory.................................................................................648
SYS_tasks() : List of active tasks in the system..................................................................................................................648
SYS_totclu() : Gets the total number of clusters on given disk..............................................................................................649
SYS_video() : Initial video mode......................................................................................................................................649
SYS_volume() : Obtains volume information for a given disk................................................................................................650
SYS_VolumeName() : Obtains volume name for a given disk...............................................................................................650
SYS_VolumeSerial() : Obtains volume serial number for a given disk....................................................................................651
SYS_winBuild() : Returns the build number of the operating system......................................................................................651
SYS_windir() : Obtains the pathname of the Windows directory............................................................................................652
SYS_WinExec() : Runs a specified application.....................................................................................................................652
SYS_WinExecEx() : Runs a specified process......................................................................................................................653
SYS_winmaj() : Returns Windows major version number.....................................................................................................654
SYS_winmin() : Returns Windows minor version number.....................................................................................................655
SYS_WriteConsole() : Writes a string to the current console.................................................................................................655
TIME FUNCTIONS................................................................................................................................................................656
TIM_ctime() : Converts a time value retrieved via TIM_time() as a character string.................................................................658
TIM_FormatMilli() : Transforms a number of milliseconds in HH:MM:SS.mmm........................................................................658
TIM_FormatTimeInterval() : Converts a time interval, specified in milliseconds, to a string.......................................................658
TIM_GetNumberOfDays() : Computes the days difference between two dates.........................................................................659
TIM_gmt() : Converts a time value retrieved via TIM_time() to an Universal Time Coordinated (UTC)........................................659
TIM_LastVersion() : Returns the file stamp of Time functions...............................................................................................660
TIM_localt() : Converts a time value retrieved via TIM_time() to a local time string.................................................................660
TIM_MakeSeconds() : Computes the number of seconds from a time string............................................................................661
TIM_MakeTime() : Computes a time value from a date........................................................................................................661
TIM_SetFormat() : Customizes the internal string buffer that TIM_UserTime() will use.............................................................661

Table Of Contents
TIM_SetSystemTime() : Sets the system time to an Universal Coordinated Time (UTC)...........................................................662
TIM_SplitMilli() : Splits a number of millseconds into its basic components (HH:MM:SS.mmm).................................................663
TIM_ticks() : Returns the number of milliseconds since Windows was started.........................................................................664
TIM_time() : Gets the current time...................................................................................................................................664
TIM_UserTime() : Gets a formatted string expressing a DateTime value.................................................................................664
TIMER FUNCTIONS..............................................................................................................................................................666
TIM_kill() : Kills the global timer.......................................................................................................................................668
TIM_proc() : Customizes the command to be executed by the global timer............................................................................668
TIM_set() : Sets the global timer......................................................................................................................................669
TMR_Create() : Creates a timer........................................................................................................................................669
TMR_Destroy() : Destroys a timer.....................................................................................................................................670
TMR_HandlesCount() : Returns the maximum number of handles.........................................................................................670
TMR_HandlesFree() : Returns the number of free timer handles............................................................................................670
TMR_info() : Returns timer information.............................................................................................................................671
TMR_LastError() : Returns an error string indicating the nature of the last error encountered....................................................671
TMR_LastVersion() : Returns the file stamp of TMR functions................................................................................................672
TMR_MaxHandle() : Returns the highest possible handle......................................................................................................672
TMR_MinHandle() : Returns the lowest possible handle........................................................................................................672
TMR_Resume() : Resumes a timer....................................................................................................................................673
TMR_Suspend() : Suspends a timer..................................................................................................................................673
APPLICATION TRACING ORIENTED FUNCTIONS.........................................................................................................................674

TRA_getlog() : Retrieves the name of the tracing log file.....................................................................................................676
TRA_LastVersion() : Returns the file stamp of TRA functions................................................................................................676
TRA_log() : Logs a string in the tracing log file...................................................................................................................676
TRA_setlog() : Sets the name of the tracing log file.............................................................................................................677
VERSION...........................................................................................................................................................................678
VER_alpha() : Gets/sets the alpha flag..............................................................................................................................681
VER_author() : Gets/sets the author name.........................................................................................................................681
VER_beta() : Gets/sets the beta flag.................................................................................................................................681
VER_cargo() : Gets/sets the cargo member. You can write whatever information you’d like to..................................................682
VER_cpyrig() : Gets/sets the application copyrights............................................................................................................682
VER_counte() : Gets/sets the application counter................................................................................................................682
VER_company() : Gets/sets the Company member.............................................................................................................683
VER_date() : Gets/sets the date field................................................................................................................................683
VER_demo() : Gets/sets the demo flag..............................................................................................................................683
VER_FinalRelease() : Gets/sets the Final Release flag..........................................................................................................684
VER_GetFileVersionInfo() : Determines executable version information..................................................................................684
VER_ini() : Gets/sets the INI file field................................................................................................................................686
VER_init() : Initializes C structure members.......................................................................................................................687
VER_LastVersion() : Returns the file stamp of VER functions................................................................................................687
VER_major() : Gets/sets the major version number............................................................................................................687
VER_minor() : Gets/sets the minor version number............................................................................................................688
VER_name() : Gets/sets the application name....................................................................................................................688
VER_prerel() : Gets/sets the pre-release flag......................................................................................................................688
VER_Release() : Gets/sets the Release flag........................................................................................................................689
VER_ReleaseCandidate() : Gets/sets the Release Candidate flag...........................................................................................689
VER_Revision() : Gets/sets the revision number.................................................................................................................690
VIDEO FUNCTIONS..............................................................................................................................................................691
VID_close() : Closes the AVI device..................................................................................................................................692
VID_end() : Sets the AVI to the end position......................................................................................................................692
VID_home() : Sets the AVI to the start position..................................................................................................................692
VID_LastError() : Determines the last error that occurred within the CD_*() functions.............................................................692
VID_LastVersion() : Returns the file stamp of VID functions.................................................................................................693
VID_loff() : Sets the AVI audio left off...............................................................................................................................693
VID_lon() : Sets the AVI audio left on...............................................................................................................................693
VID_off() : Sets the AVI audio off.....................................................................................................................................694
VID_on() : Sets the AVI audio on.....................................................................................................................................694
VID_open() : Opens the AVI device..................................................................................................................................694
VID_play() : Plays the AVI device.....................................................................................................................................694
VID_pause() : Pauses the AVI device................................................................................................................................695
VID_ron() : Sets the AVI audio right on.............................................................................................................................695
WHOIS FUNCTIONS...........................................................................................................................................................696
WHOIS_LastError() : Last error encountered in WHOIS functions..........................................................................................698
WHOIS_LastVersion() : Returns the file stamp of WHOIS functions.......................................................................................698
WHOIS_whois() : Queries a central repository for information regarding users, hosts, company addresses, and phone numbers.. .698
WINDOWS FUNCTIONS.........................................................................................................................................................702
WIN_bottom() : Window bottom border position in pixels....................................................................................................704
WIN_ClearOval() : Deletes an elliptical region created with WIN_MakeOval()..........................................................................704
WIN_Destroy() : Destroys the specified window.................................................................................................................705
WIN_DestroyIcon() : Destroys a given icon........................................................................................................................705
WIN_dialog() : Displays a dialog box that is the specified color scheme and contains the specified body text and button text........706
WIN_DrawAnimatedRects() : Draws a wire-frame rectangle and animates it to indicate the opening of an icon or the minimizing or
maximizing of a window..................................................................................................................................................706

Table Of Contents
WIN_DrawEdge() : Draws one or more edges of rectangle...................................................................................................707
WIN_DrawIcon() : Draws a given icon...............................................................................................................................708
WIN_EnumChildren() : Enumerates the child windows that belong to the specified parent window............................................709
WIN_EnumWindows() : Enumerates all top-level windows on the screen...............................................................................710
WIN_Flash() : Flashes the specified window once...............................................................................................................711
WIN_GetActiveWindow() : Retrieves window handle (HWND) of the current window...............................................................711
WIN_GetChildren() : Retrieves all child window handles obtained by a call to WIN_EnumChildren()...........................................711
WIN_GetClassName() : Retrieves the name of the class to which the specified window belongs................................................712
WIN_GetClientArea() : Retrieves the dimensions of the bounding rectangle of the specified window..........................................713
WIN_GetExStyle() : Retrieves the extended window styles...................................................................................................714
WIN_GetForegroundWindow() : Returns a handle to the foreground window (the window with which the user is currently working).
....................................................................................................................................................................................714
WIN_GetHandle() : Retrieves a handle to the top-level window corresponding to the passed parameter.....................................715
WIN_GetHInstance() : Retrieves the handle of the application instance that handles a given window.........................................715
WIN_GetHwndParent() : Retrieves the handle of the parent window, if any............................................................................716
WIN_GetIcon() : Extracts a given icon from an executable or DLL.........................................................................................716
WIN_getPort() : Returns the WHANDLE of the window that is currently selected for user output................................................717
WIN_GetStyle() : Retrieves the window style.....................................................................................................................718
WIN_GetWindowDC() : Retrieves the device context (DC) for the entire window, including title bar, menus, and scroll bars.........719
WIN_GetWindows() : Retrieves all window handles obtained by a call to WIN_EnumWindows()................................................719
WIN_GetWindowText() : Determines a window's title bar....................................................................................................720
WIN_GetWndProc() : Retrieves the address of the window procedure, or a handle representing the address of the window
procedure......................................................................................................................................................................720
WIN_handle() : Window handle (WHANDLE)......................................................................................................................721
WIN_height() : Window height in pixels.............................................................................................................................721
WIN_hwnd() : Returns the Windows HWND of a given window.............................................................................................722
WIN_IsWindow() : Determines whether the specified window handle identifies an existing window...........................................722
WIN_IsWindowEnabled() : Determines whether the specified window is enabled for mouse and keyboard input..........................722
WIN_IsWindowUnicode() : Determines whether the specified window is a native Unicode window.............................................723
WIN_IsWindowVisible() : Determines whether the specified window is visible or not...............................................................723
WIN_LastVersion() : Returns the file stamp of WIN functions...............................................................................................724
WIN_left() : Window left border position in pixels...............................................................................................................724
WIN_Lock() : Disables or re-enables drawing in the specified window....................................................................................724
WIN_main() : Desktop window handle (WHANDLE).............................................................................................................725
WIN_MakeOval() : Creates an elliptical region and attach it to a form....................................................................................725
WIN_MsgBox() : Creates, displays, and operates a message box..........................................................................................726
WIN_raised() : Draws a raised edge of rectangle................................................................................................................729
WIN_ReleaseDC() : Releases a device context (DC), freeing it for use by other applications.....................................................730
WIN_right() : Window right border position in pixels...........................................................................................................730
WIN_Select() : Brings the specified window to the active position on the screen.....................................................................731
WIN_SetActiveWindow() : Redirects Windows output to the window asociated with this handle (HWND)....................................732
WIN_SetFocus() : Sets the keyboard focus to the specified window......................................................................................733
WIN_SetFocusS() : Shows a window and bring it on top......................................................................................................733
WIN_SetForegroundWindow() : Puts the thread that created the specified window into the foreground and activates the window.. 734
WIN_SetParent() : Changes the parent window of the specified child window.........................................................................735
WIN_setPort() : Changes the user output window to be the specified window.........................................................................735
WIN_sunken() : Draws a sunken edge of rectangle.............................................................................................................736
WIN_top() : Window top border position in pixels...............................................................................................................737
WIN_width() : Window width in pixels...............................................................................................................................737
WIN_WHandleToHwnd() : Returns the Windows HWND of the specified WHANDLE..................................................................738
ZIP FUNCTIONS.................................................................................................................................................................739
MEM_Compress() : Compresses a string............................................................................................................................741
MEM_Decompress() : Decompresses a string compressed with MEM_Compress()....................................................................742
ZIP_Compress() : Compresses a set of files into a ZIP archive..............................................................................................743
ZIP_Expand() : Expands all files contained in a ZIP archive..................................................................................................744
ZIP_LastError() : Determines the last error that occurred within the ZIP_*() functions.............................................................744
ZIP_LastVersion() : Returns the source file stamp of ZIP functions........................................................................................745
ZIP_List() : List all files contained in a ZIP archive..............................................................................................................745
ZIP_SetCallback() : Gets/Sets a callback function for the ZIP_Compress(), ZIP_Expand() and ZIP_List() functions......................746
ZIP_SetSubdirs() : Gets/Sets the subdirectory flag as used in ZIP_Compress()......................................................................747

Copyright Notice & Disclaimer
Software License for FOCUS.FLL
Terms of Use
FOCUS.FLL is copyrighted shareware, not public-domain software. All source code and documentation contained in the
present notes is exclusive material and has been developed at FastWrite s.c.r.l.. As part of our service, FastWrite
s.c.r.l. agrees to provide freely downloadable evaluation versions of this software. FastWrite s.c.r.l. agrees to provide
this service free of charge You may use the unregistered version for an evaluation period of 60 days only. To
continue to use the software beyond the 60-day evaluation period, you must register it.
Upon notice published by FastWrite, FastWrite s.c.r.l. may amend or modify these Terms of Use at any time. You agree
to use the service in accordance with the Terms of Use.
Copyright Notices
The product is owned by FastWrite s.c.r.l.. All rights in the product including, copyrights, licensing rights, patents,
trademarks, trade secrets, design rights, engineering rights, moral rights, and any other intellectual property rights
belong to FastWrite. These rights are not transferred as part of this agreement.
End User License Agreement
This license agreement is a legal agreement between you the end user (either as an individual or an entity) and
FastWrite s.c.r.l. herein after referred to as FastWrite. The software and any of its supporting documentation are
herein after referred to as the product.
By purchasing, installing or using the product, you indicate your complete and unconditional acceptance of these terms
and conditions. If you do not agree to the terms and conditions of this agreement promptly remove the product from
your computer and destroy the associated documentation.
Should there be any conflict between the terms and conditions of this agreement and the terms and conditions of any
other agreement between you and FastWrite or their servants or agents in relation to the product the terms and
conditions of this agreement shall prevail.
If any provision of this agreement is found to be unlawful or void then that provision shall be severed from this
agreement and will not affect the validity of the remaining provisions. You will accept any new lawful provision
replacing the deleted clause and having an equivalent economic effect.
Information contained in the product is subject to change without notice and does not represent a commitment or
contracted obligation on the part of FastWrite.
Limitations of Use
You are expressly forbidden to develop more than one program associated to the product per registration. A new
registration is thus compulsory for each new development associating the product.
You are expressly forbidden from making alterations or modifications to, merge, adapt, de-compile, disassemble,
reverse engineer, or attempt to discover the source code without the expressed written permission from FastWrite. You
are expressly forbidden from using any part of the evaluation version of the product but for evaluation purposes
excluding any commercial or non-profit development as well as development for internal or private purposes.
You may use, modify, copy, distribute, and demonstrate any source code published in the documentation, example
programs, or documentation herein contained. This is to the sole exclusion of the library itself, namely the physical
files FOCUS.FLL and KERNEL.DLL.
You shall take the necessary steps in order to prevent any user of any program associated to the product from
developing and/or distributing new programs including the licensed product hereunder and shall notify FastWrite
s.c.r.l. in writing of the identity and address of any user of a program associated with the product. The latter clause is
of the essence of this agreement.
The programs developed by you and using the product FOCUS.FLL shall contain the full text of this license agreement.
FastWrite reserves the right to make changes to the specifications of the program and contents of the manual without
obligation to notify any person or organization of such changes.

Copyright Notice & Disclaimer
Limitations of liability
Under no circumstances, including, but not limited to, negligence, shall FastWrite s.c.r.l., its subsidiary or affiliates be
liable for any direct, indirect, incidental, special or consequential damages that result from the use of, or the inability
to use, the product.
All the work contained herein and in the product is only intended as a pure illustration of basic concepts that apply to
Visual FoxPro development. It is distributed in the hope that it will be useful but is provided on an "as is" basis, with no
implied warranty regarding merchantability or fitness for any particular purpose. FastWrite s.c.r.l. and the author will
not be liable for any damages, no matter how severe they are, real or imagined, direct or indirect resulting from the
use of this software and documentation. FastWrite s.c.r.l. does not warrant that the functions contained in the
materials will be uninterrupted or error-free, nor that defects will be corrected.
With regard to the evaluation period freely granted by FastWrite s.c.r.l., no claim concerning the product shall be
admissible for any reason whatsoever.
If you are dissatisfied with any part of the product, or with any of FastWrite s.c.r.l. terms and conditions, your sole and
exclusive remedy is to discontinue using the product. In addition, You release FastWrite s.c.r.l. and its affiliates from
any damages that you incur, and agree not to assert any claims against them, arising from your use of it's products or
services.
In no way shall Fastwrite s.c.r.l. be liable for an amount exceeding the price of the product.
Breach of contract
You acknowledge that any breach of this agreement shall cause FastWrite s.c.r.l. irremediable harm and that FastWrite
s.c.r.l. reserves the right to claim damages in such occurrence with a minimum penalty of EUR 10,000.00 (ten
thousand euros and no cents).
Applicable law and venue
This agreement is governed by the laws of Belgium.
Any dispute arising out of or in connection with this agreement shall be of the sole jurisdiction of the commercial court
of Nivelles.

Introduction
Thank you for your interest in FOCUS. We have made every effort create a valuable collection of Visual FoxPro tools.
We are constantly improving this library, so you may want to check our Web site ( http://www.fastwrite.com .)
regularly to download newer versions
We have developed FOCUS at FastWrite s.c., a long time ago. This project is actually rooted in Clipper. In fact it all
started in 1990 while we were developing Do-It!, a powerful library designed especially for Clipper Autumn '86.
As the project continued, we included more and more functions in Do-It! Many of them were developed in Assembler,
and C. From time to time we also included Clipper functions as well, as the Clipper compiler produced .OBJs.
Do-It! was also accompanied with a powerful screen generator, The Builder. Many functions that we have included in
Do-It! were just needed by the screen generator. We have updated Do-It! With the many new versions of Clipper :
Summer '87, then Clipper 5.0, finally Clipper 5.2. We thought that nothing was worse than this step : adapting our
library to new versions of the language. This process has led us to "subclass" all Clipper routines to ours, a treatment
we called "code floating". We have passed from Lattice C, to Microsoft C 4.0, then Microsoft C 5.0. From Microsoft
Macro Assembler 4.0 to 5.0 ... and we have survived them all!
In 1993, we saw the BIG change : turning Do-It! to FoxPro 2.5 for Windows. Not only the language was different, but
so was the target operating system—Windows 3.11. Many of the Assembler routines we have created were simply not
portable to Windows code. The Clipper code called many features that FoxPro didn't support : static variables, multi-
dimensional arrays (we're talking about arrays whose each individual element can be in turn an array), code blocks
(pointers to functions if you want, but much more than that), and also powerful preprocessor. Basically all the Clipper
code had to be removed and because FoxPro didn't (still doesn't) produce real .OBJs we could not turn any Clipper
code to FoxPro in order to include this code in the library itself. Additionally, we have gone away from Microsoft C 5.0
in favor of Microsoft Visual C++ 1.0, 1.5, 2.0, and 2.2.
That was a major earthquake but we eventually did it. We have adapted our "subclasses" to FoxPro API routines; we
have turned our old DOS code to Windows code; we have fine-tuned the memory allocation routines to properly avoid
the infamous GPFs! We grab the opportunity of these major changes to introduce a new one : we change from Do-It to
FOCUS. After this work has been completed we once again updated FOCUS to work with a new version of FoxPro—
version 2.6.
In 1995, we have once more introduced a major change : the shift to a new paradigm with the introduction of Visual
FoxPro 3.0. Call it evolution or revolution, we called it a nightmare! Not only was the version of FoxPro different, but
we also faced for the first time the importance of 32-bit code. Yes ... we were obliged to replace our old 16-bit code
with 32-bit code. We have simplified our task in the sense we decided not to support the 16-bit platform anymore,
namely Windows 3.11 and the like.
Once again, we updated our code to be compatible with Visual FoxPro 5.0. That was very easy ... for the first time! So
easy, that we actually decided once to have a library that would work for both versions. We did it for several months
up to the moment we only supported version 5. But the miracle is that FOCUS seems to be compatible, without any
change, with version 6. A miracle, we say.
Today, FOCUS is designed to suit any need (we hope) in the 32-bit environment, that is Windows 95, Windows 98 and
Windows NT. Although some of our machines are already equipped with Windows 98, we haven't performed any test
yet. We'll see what the future brings.
You may ask, why not develop classes as well? We did. In November 1996 we have announced FOCUS classes on
CompuServe although we didn't grab much attention from the FoxPro community. That was surprising to us as
FOCUS.FLL was such a success (more than 8.000 downloads). Perhaps we came too late with our classes?
The classes we planned to distribute included features not seen anywhere else. Of course, because we used our own
library and classes in our projects, some of the features were geared to our own way of doing things. We in Belgium,
for example, have a special need for multi-lingual applications : we have 3 national languages (yeah ... for such a
small country). That's the reason why we have included many features that you can also find in Steven Black Intl
product, a flagship product. Anyone serious with multi-lingual needs should get his development arsenal. Multi-lingual
needs drove us to develop Artificial Intelligence routines, a feature that's not available in any other library of classes,
we can assure you.
FOCUS.VCX grew up very rapidly and has known a number of revisions. We have rebuilt FOCUS.VCX many times;
we have "childed" FOCUS.VCX with POINTDBF.VCX , FOCUS2.VCX , etc. Now we're back with our original
FOCUS.VCX , cleaned up from many features that are only suitable for us. FOCUS.VCX can be obtained from our
Web Site (http://www.fastwrite.com ) and is constructed as a wrapper around FOCUS.FLL . Of course we have
developed many additional classes. And like many other libraries it provides an application framework (which is by no
means the last word on frameworks ... see also the fabulous work of Alan Griver with CodeBook, or the incredible

Introduction
framework developed at MaxTech, Inc by Drew Speedie). FOCUS.VCX is not documented yet (although we plan to
document both the FLL and the VCX herein). Go to our Web Site to follow a tutorial on these classes.
Sorry
From time to time (or very often) you might find English mistakes all along this document. This is due to the fact that
the authors are non native English persons. We sincerely apologize for this. Should anyone want to correct some parts
of this document, he (or she) is very welcomed.
Writing code can be a team effort, but in the case of FOCUS.FLL it is mostly a solo activity. So was the documentation
… up to October 98, period at which Pete Cuiry turned words into prose and reviewed the documentation. "Pete, you
went above and beyond the call of duty. Thank you".
Most Common Questions

1. What library do I have to use with Visual FoxPro?
You need 2 dynamic link libraries:
1. FOCUS.FLL
2. KERNEL.DLL .
FOCUS.FLL is the only library you'll consciously deal with. However, FOCUS.FLL uses KERNEL.DLL internally.
FOCUS.FLL should be available in your project directory (the directory of your application). KERNEL.DLL should be
placed in the SYSTEM directory of Windows (most likely C:\WINDOWS\SYSTEM for Windows 95 or
C:\WINNT\SYSTEM32 for Windows NT 4.0). KERNEL.DLL cal also be placed in the application's home directory.
2. Invalid library.
FOCUS.FLL depends on KERNEL.DLL to work correctly. Both files work with each other. FOCUS.FLL should be
placed in the home directory of the application you need FOCUS.FLL for, and KERNEL.DLL is best placed in the
System directory of Windows.
3. FOCUS.EXE|KERNEL.EXE is not a valid Win32 application.
When downloading FOCUS.FLL and KERNEL.DLL from Web sites, some browsers assign an .EXE extension to the
files when saving them to your hard disk. Should this happen, simply rename FOCUS.EXE to FOCUS.FLL or
KERNEL.EXE to KERNEL.DLL . This should solve the problem.
4. What are long function names?
Long function names are available to Visual FoxPro developers that want to take advantage of improved readability
rather than to stick with 10 character function names. It is indeed simpler to use FIL_ReadIni() than
FIL_reaini() , even though both names point to the same internal service. Long function names are usually aliases.
5. What is an alias?
FOCUS.FLL treats aliases as alternate names for the same function. It helps developers to find the function they want
to use according to a logical category. When such functions can be placed under different categories, they are most
likely available under each category. That makes it very simple to find them. On the other hand, when such functions
are also known from other libraries, the alias technique makes it simple to keep calling the same function, even if it is
in fact called differently in FOCUS.FLL itself. For example, consider the SYS_dskspa() function that returns the
number of bytes that are currently available on a specified disk drive. This function can also be called with
DiskRoom() , SYS_DiskSpace() , SYS_DiskSpaceLeft() , or SYS_DiskEmpty() .
Under construction
Some functions are indicated as being under construction. These functions have been requested and accepted by
FastWrite but are not implemented yet. However, you can expect to get these ... one of these days!

Introduction
Web Site
You can find the latest information as well as on-line documentation about FOCUS on our web site:
http://www.fastwrite.com/products/focus .

Change Control
Change Control
With version 7.87 of FOCUS.FLL we have introduced the Change Control Table so that you can follow what changes
have been made to FOCUS.FLL . Change Control is also a necessity to comply with a set of rules such as FDA CFR Title
21 Part 11. With it, you can rest assured that your library remains in full compliance with the rules of your industry.
Version Date Description of the Changes

7.86
Introduction of FTP functions
7.87 27 August 2000 1. COM functions reworked – still temporary state
2. Files.c reworked (FIL_ReadByte() modified,
FIL_GetUniversalName() added). No code impact.
3. Win.c reworked WIN_SetForegroundWindow() with
SetForegroundWindow() alias. No code impact.
4. Misc.c reworked, MIS_false() updated, MIS_true() updated,
MIS_argc() updated, MIS_argv() updated. No code impact.
5. Focus.c reworked to add new alias definitions, better syntax support, and
better code standardization.
6. Start on conversion for FOCUS.FLL 8.x
7. Start working on integration for FOCUS.FLL "Small Footprint" – available
after FOCUS.FLL 8.0 will be launched.
8. Start working on new Internet functions: HTTPS, Gopher, SMTP, POP3,
Ping, WhoIS, News and Finger.
9. Start working on the integration of many ActiveX controls that will
complete the FOCUS product line offering.
10. Start working on the integration of MAPI functions by reworking the
FOCUMAPI.FLL code.
11. Locale.c reworked to add functions to enumerate the installed locales:
LOC_EnumSystemLocales() and LOC_GetSystemLocales() . No
code impact.
12. Win.c: WIN_MsgBox() documentation reviewed.
13. SYS_IsNT() documentation updated to accommodate Windows 2000.
14. Documentation updated
7.88 22 September 2000 1. MAPI.c: first set of MAPI functions – very temporary state
2. NTEvent.c : first set of NTEvents functions - very temporary state
3. FTP.c : FTP_CloseAllSessions() added.
4. VER_GetFileVersionInfo() documentation updated
5. List of dependencies introduced on the Web Site and in the documentation
6. STR_GeneratePassword() : new function
7. HTTP_LastGetURLTime() : new function
8. HTTP_GetURL() : accepts an optional new parameter. No code impact.
9. NET_LastError() : NET_*() functions do comply with «Last Error»
strategy which means that now the developer can obtain extended
information concerning the last "Network" operation. No code impact.
10. NET_EthernetAddress() : the parameter is now optional. If not passed,
the full Ethernet Address is returned. No code impact.
11. NET_ConnectionDialog() : compliant with «Last Error» strategy.
Accepts an optional parameter (Resource Type). No code impact.
12. _retdw() : has been introduced to the EXTEND.H interface file. Impact
on all sources. No code impact.
13. NET_GetConnection() : the function has been suppressed and mapped
to an alias of the FIL_GetUniversalName() function. No code impact.
14. FIL_GetUniversalName() has now 2 additional aliases:
NET_GetConnection() and NET_GetUniversalName() .
15. DDA_GetSto() , DDA_GetStop() ,DDA_GetStopProc() , are all aliases
of the same function. The dynamic syntax has been updated. No code
impact.

Change Control
16. DDA_LastVersion() : the dynamic syntax has been updated. No code
impact.
17. NET_CancelConnection() : WNetCancelConnection() and
WNetCancelConnection2() are 2 new aliases. Possible code impact for
people having declared these services as Win32 API services.
7.89 17 October 2000 1. SND_play() : the second parameter is now optional. No code impact.
2. HTTP_CombineURL() : new function.
3. SYS_LastError() : This function has been renamed
SYS_LastErrorCode() and SYS_LastError() now returns an error
string instead of an error code. Possible code impact.
4. HTTP_CrackURL() : new function. No code impact.
5. HTTP_IsURL() : new function. No code impact.
6. All EVE_*() functions have been reworked and new functions have been
introduced. No code impact.
7. New syntaxes supported in the list of dynamic syntax identifiers.
7.90 21 October 2000 1. STR_Like() : new function (in test)
2. STR_LikeGetToken() : new function (in test).
3. DBF_Skip() : new function.
4. FIL_WriteIni() : the function now flushes all Windows INI cache.
Possible code impact (very unlikely).
7.92 14 February 2001 1. PRN_SetDefaultPrinter() : old function that got documented.
2. STR_*() : whole module rewritten.
3. HTTP_*() : whole module rewritten.
4. FIL_*() : whole module rewritten.
5. FTP_*() : whole module rewritten.
7.93 1 March 2001 1. SYS_IsDriveReady() : whole code rewritten. Potential code impact.
Please notice that the previous code didn't work at all.
2. SYS_DiskSpace() : support for large drives. No code impact.
3. SYS_DiskSize() : support for large drives. No code impact.
7.94 20 May 2001 1. STR_nSet() : Takes an additional parameter to indicate where the string
needs to be processed. This parameter is optional. No code impact.
2. STR_like() : Takes 2 additional parameters: an optional LastMatch
parameter, and the position the string needs to be processed.
3. MQSeries functions implemented within FOCUS.FLL . FOCUS.FLL won't
load unless MQSeries1 (Server) will be present on the machine. These
functions are simply commented out for the time being. They will certainly
be extracted from FOCUS.FLL to form 2 brand new FLLs:
FOCUSMQS.FLL (server) and FOCUSMQC.FLL (client). No code impact.
4. IP_ping() : documented. The function was present but was not
documented. No code impact.
5. SPI_GetWorkArea() : This function was not supported by Windows NT.
Now, in Windows 2000, it is! The function copes with that distinction. Minor
code impact.
7.95 14 July 2001 1. STR_AtLine() : this function was introduced with version 7.94 but was
left undocumented. No code impact.
2. SPI_GetWorkArea() : unexpected MessageBox() removed.
3. SYS_processes() : compatible with Windows NT via the PSAPI.DLL
system DLL. Minor code impact because the function wasn't working at all
before (at least under NT).
4. SYS_EnumDeviceDrivers() : new function. Only works with Windows
NT. No code impact.
5. MTH_factorial() : documented + new alias created
MTH_factorielle() . No code impact.
6. MTH_combinations() : new function. No code impact.
7. MTH_permutations() : new function. No code impact.
8. Few functions of MQSeries documented (creation of FOCUSMQS.FLL and
FOCUSMQC.FLL ).
9. STR_Like() : accepts a second parameter sent by reference. No code
impact.
10. ARR_elements() : new function. No code impact.
11. ARR_rows() : new function. No code impact.
12. ARR_columns() : new function. No code impact.
13. ARR_LastVersion() : new function. No code impact.
1
MQSeries is a product of IBM for Queue Messaging

Change Control
14. Documentation update.
15. STR_ltrim() : this function was left undocumented. Now it is part of the
documentation. No code impact.
16. STR_rtrim() : this function was left undocumented. Now it is part of the
documentation. No code impact.
17. PRN_dialog() : documentation corrected.
18. IP_GetIP() : new function. No code impact.
19. STR_TrimLeft(): Trims off x characters from the left of a string. New
function. No code impact.
20. STR_TrimRight(): Trims off x characters from the right of a string. New
21. FIL_crypt(): Function is now operational. No code impact.
22. FIL_decrypt(): Function is now operational. No code impact.
23. FIL_ReadSub(): New function. Reads a portion of a file (similar to
SUBSTR() on files!). No code impact.
7.96 14 November 2001 1. KEY_HookF12() : new function. No code impact.
2. KEY_UnHookF12() : new function. No code impact.
3. KEY_HookF12Proc() : new function. No code impact.
4. KEY_HookPrtScr() : new function. No code impact.
5. KEY_UnHookPrtScr() : new function. No code impact.
6. KEY_HookPrtScrProc() : new function. No code impact.
7. PRN_GetJobs() : New function. No code impact.
8. TIM_SetFormat() : Returns a string instead of a logical .T.. Possible code
impact.
9. FIL_common() : New function. No code impact.
10. FIL_Canonicalize() : New function. No code impact.
11. SHE_AddIcon() : New function. No code impact.
12. SHE_DeleteIcon() : New function. No code impact.
13. SHE_DeleteAllTrayIcons() : New function. No code impact.
14. SYS_HookWindowsProc() : New function. No code impact.
15. SYS_UnHookWindowsProc() : New function. No code impact.
16. SHE_SetTrayIconProc () : New function. No code impact.
17. FIL_IsUNC() : New function. No code impact.
18. STR_Replace() : Replaces a substring with another in a string.
19. Correcting a bug in FIL_Decrypt() . No code impact.
20. FIL_BrowseForFolders() : The context menu control has been
removed + new textbox. Possible, but limited, code impact.
21. HTML_Encode() : New function. No code impact.
7.97 20 November 2001 1. HTTP_GetCookie() : new function. No code impact.

2. SHE_GetSettings() : this function was introduced in 7.96 but was left
undocumented. It should have no code impact. However, this function
caused the DLL to be reported invalid on many systems. Instead of making
a direct call to SHGetSettings(), we now LoadLibrary( "shell32.dll" )
and try to obtain the function pointer via GetProcAddress(). This
implementation is safer than the previous one.
7.98 03 March 2002 1. FIL_save() : new function. Save File Dialog Box. No code impact.
Alias = DLG_save() .
2. EDI_FileName() : Determines the name of the file that is currently
edited. This function was included in FOCUS.FLL for a long time but has
only been documented with version 7.98.
3. SYS_P3Serial() : new function. No code impact. please notice that
the user has the ability to switch off the publication of its serial number in
which case the function returns simply an empty string.
4. FIL_IsUNC() : documented.
5. PRN_GetJobs() : documented.
6. FIL_Canonicalize() : documented.
7. FIL_Common() : documented.
8. SHE_DeleteAlltrayIcons() : documented.
9. PRN_EnumPrinters() : Enumerates available printers. new function.
No code impact.
10. REG_GetData() : can now handle REG_DWORD values. Minor code
impact.
11. FIL_IsDirShared() : is a given directory shared? New function. No
code impact. This has been implemented as an alias of FIL_IsShared()
which remains valid.
12. FIL_IsShortcut() : is a given file object a shortcut? New function.
Change Control
No code impact.
13. STR_Encode64() : base64 encoding. New function. No code impact.
14. STR_Decode64() : base64 decoding. New function. No code impact.
15. DDA_SetStop() :bug corrected. Documentation corrected. Minor code
impact.
7.99 24 March 2002 1. NET_InternetTime() : new function. Atomic clock setting. No code
impact.
2. HTTP_GetURL() : Modification of the original function. Now the function
uses Winsock instead of Wininet. Major code impact even though the
parameters are still the same.
3. HTTP_GetURL2() : Rename of the original HTTP_GetURL() function.
Uses Wininet instead of Winsock.
4. STR_Hexa() : speed improvement up to a factor of 3000. The function is
now also capable to deal with binary data.
5. STR_htos() : speed improvement and bug fix. The function is now also
capable to deal with binary data.
6. HTTP_GetURL() : minor bug fix when reading HTTP headers. No code
impact.
7. CLP_SetText() : new function. No code impact.
8. STR_*() : compatible with entry/exit macros for advanced debugging.
9. CLP_*() : compatible with entry/exit macros for advanced debugging.
10. ARR_*() : compatible with entry/exit macros for advanced debugging.
11. BMP_*() : compatible with entry/exit macros for advanced debugging.
12. internal syntax array externalized. Potential code impact if the
focussyntax.txt is not present in the System directory of Windows.
13. When FOCUS.FLL loads in memory, it grabs more system information about
the current process (your application). It helps FOCUS.FLL to better cope
with system internals when you call a single function.
14. SYS_*() : compatible with entry/exit macros for advanced debugging.
15. SYS_IsLoaded() : determines whether a given EXE or DLL is loaded. New
16. SYS_GetEnvironmentStrings() : although the function has been
around for a while it hasn't been documented so far. Now the function is
safe to use. Can be considered as a new function and therefore should
have no code impact.
17. SYS_WriteConsole() : new function. No code impact.
18. SYS_AllocConsole() : new function. No code impact.
19. SYS_FreeConsole() : new function. No code impact.
20. SYS_GetStdHandle() : new function. No code impact.
21. SYS_GetConsoleHWND() : new function. No code impact.
22. SYS_GetConsoleTitle() : new function. No code impact.
23. FW_SYS_SetConsoleTitle() : new function. No code impact.
8.0 1 September 2002 1. PRN_GetDefaultPrinter() : new function. No code impact.

2. STR_FindBackward() : new function. No code impact. BOYER algorithm.
3. STR_Find() : new function. No code impact. BOYER algorithm.
4. DAT_doy() : new function. No code impact. Returns the day of the year
for a specific date.
5. HTTP_GetURL() : a timeout mechanism has been introduced. The string
that is returned can be as large as needed to the opposite of the 512Kb of
the original function. No code impact (GET method).
6. HTTP_PostURL() : new function. No code impact (POST method).
7. HTTP_SetURLTimeout() : new function. No code impact. Set the timeout
value for HTTP_GetURL() , HTTP_GetURL2() and HTTP_PostURL()
functions.
8. WHOIS_whois() : new function. No code impact.
9. STR_ntoken() : new optional parameter (start position). No code impact.
10. STR_numtok() : new optional parameter (start position). No code impact.
11. STR_ntokenEx() : same as STR_ntoken() but ALL parameters are
mandatory). New function. No code impact.
12. ARR_min() : determines the minimum of all numeric elements of an array.
New function. No code impact.
13. ARR_max() : determines the maximum of all numeric elements of an
array. New function. No code impact.
14. ARR_average() : determines the average value of all numeric elements of
an array. New function. No code impact.

Change Control
15. REG_EnumKeyEx() : retrieves all subkeys associated with a given key of
the registry. New function. No code impact.
16. ARR_create() : creates an array of given dimensions. New function. No
code impact.
17. ARR_IsArray() : determines if parameter is an array or not. New
18. ARR_Dimensions() : determines the dimensions (rows and cols) of an
array. New function. No code impact.
19. SCR_GetFullScreenDimensions() : determines the usable dimensions
of the Windows desktop (Desktop area). New function. No code impact.
20. SCR_GetScreenDimensions() : determines the dimensions of the
Windows desktop (Desktop area minus the system tray area). New
21. WIN_MakeOval() : determines the dimensions of the Windows desktop
(Desktop area minus the system tray area). New function. No code impact.
22. STR_AllChars() : New function. No code impact.
23. STR_soundex() : New function. No code impact.
24. STR_SetLikeCharConversion() : New function. No code impact.
Influence on STR_Like() that otherwise remains unchanged.
25. STR_Like() : function modified. It does not set the wildcard buffer to
NULL s (improvement in performance) and it does take character
conversions into account (without performance degradation). The algorithm
is also faster when patterns are not star terminated. In case of long
patterns, the function uses also an internal improvement by performing a
BOYER-MOORE search on the first word of the pattern. As the code has
been profoundly changed, it may have a potential code impact.
26. STR_ResetLikeCharConversions() : New function. No code impact.
8.01 8 October 2002 1. STR_Like() : turning optimization off because of some weird problems on
some strings. We will have to rework our fast string search algorithm.
2. STR_strstr() : new function. No code impact. However, the function is
not yet documented and should not be used by the developers before
FastWrite gives the green light.
8.02 12 October 2002 1. STR_FndExe() : internal bug corrected (no impact on the VFP code).
Documentation reflects what the function really does now.
2. RG_Compile() : first introduction of Regular Expressions inside
FOCUS.FLL . Before long, all functions that were once created in the
FOCUSReg.dll, will be included in FOCUS.FLL for ease of use. The
RG_Compile() function works fine but we recommend not using it so
far.
3. RG_Execute() : first introduction of Regular Expressions inside
FOCUS.FLL . Before long, all functions that were once created in the
FOCUSReg.dll, will be included in FOCUS.FLL for ease of use. The
RG_Execute() function works fine but we recommend not using it so
far.
4. Documentation has been reviewed and many inconsistencies were
corrected.
5. HTTP_GetDefaultBrowser() : new function. No code impact.
Determines the location of the default browser.
6. NUM_BinHi() : new function. No code impact. Determines the high byte
value of a number.
7. NUM_BinLow() : new function. No code impact. Determines the low byte
value of a number.
8.03 12 January 2003 1. LOG_Append() : internal bug fixed when strategy set to “Reduce to Half
Size”.
2. EnumWindows() : this was an internal alias of WIN_EnumChildren() .
This is no longer the case as it became the alias of WIN_EnumWindows() .
Potential code impact.
3. GetWindows() : this was an internal alias of WIN_GetChildren() . This
is no longer the case as it became the alias of WIN_GetWindows() .
4. WIN_EnumWindows() : new function. No code impact. Initiates the

Change Control
retrieval a list of top-level windows of Windows.
5. WIN_GetWindows() : new function. No code impact. Completes the
retrieval of the list of the top-level windows started via
WIN_EnumWindows() .
6. WIN_BringWindowToTop() : new function. No code impact. Was kept
internal to FOCUS.FLL . We have finally decided to document it.
7. SYS_GlobalMemoryStatus() : bug fix. The size returned by the
function couldn't fit with large memory as we find in the computers
nowadays. The visible effect was that the number returned was a negative
number. This has been corrected to return a positive number instead.
8. SYS_ExitProcess() : new function. Makes it possible to return an error
level to the calling application or ,command file. No code impact.
9. TIM_MakeTime() :Correction of a vicious bug that happened when the
function was called at a moment when the local time expression was laying
into another day than the GMT time (for example GMT is 23PM and local
time is 01AM). Potential code impact.
10. ARR_average() :Correction of a bug on one-dimensional arrays Potential
code impact.
11. MET_FeetToMeters() : a metric function to convert feet to meters. New
12. MET_MetersToFeet() : a metric function to convert meters to feet. New
13. NUM_gcd() : Euclid's implementation of the greatest common divisor of
two integers. New function. No code impact.
14. NUM_UniversalID() : creates a globally unique identifier of 66 bytes
maximum. Use this function when you absolutely need a unique number
that you will use as a persistent identifier in a distributed environment. To
a very high degree of certainty, this function returns a unique value – no
other invocation, on the same or any other system (networked or not),
should return the same value. The algorithm that is followed assures that
the ID is unique in space and unique in time.
15. The Test Status grid of each function has been removed.
16. Font functions are gone (FNT_*() ) as announced in 2002.
17. User functions are gone (USR_*() ) as announced in 2002.
8.04 22 February 2003 1. FIL_CreateHardLink() : creates a new logical name for a file and
referring to the file with that logical name. Very similar to UNIX. New
2. Introduction of TAO functions. Even though simple, and maybe seen by
some programmers as useless, empty functions make it possible to return
results from basically any input. This makes them very suitable to build
long expressions that are nothing else but chaining of commands. TAO
functions were existing in FOCUS for a long time but they were kept sparse
(consider MIS_nothing() for example). Now all the same functions have
been gathered in one source. All TAO_*() functions are totally new and
hence do not have any code impact.
3. PRN_GetJobs() : internal bug corrected. Code impact.
4. PRN_GetJobInfo() : new function. No code impact.
5. TAO_false() : returns always .F.. New function. No code impact.
Identical to MIS_false() .
6. TAO_true() : returns always .T. . New function. No code impact. Identical
to MIS_true() .
7. TAO_string() : returns always "". New function. No code impact.
Identical to STR_null() .
8. TAO_datetime() : returns always { / / : : } . New function. No code
impact.
9. NUM_base() : converts the digits of a given integer argument to a string,
by taking into account a given radix. New function. No code impact.
10. STR_FormatByteSize() : Converts a numeric value into a string that
represents the number expressed as a size value in bytes, kilobytes,
megabytes, or gigabytes, depending on the size. New function. No code
impact.
11. TIM_FormatTimeInterval() : Converts a time interval, specified in
milliseconds, to a string. New function. No code impact.
12. HTML_Decode() : the function was present in the library but was not
documented. New function. No code impact.

Change Control
13. HTTP_GetURL2() : the function uses a bigger temporary buffer and is
now much faster than previously. A bug has been removed in the function
(endless loop in case of lost server connection). The function has been
documented (it wasn't before) and does not accept a second parameter
anymore (optional memory). For those of our users that didn't use the
function yet, there should be no code impact. For the others, please
make sure that the second parameter isn't used anymore.
14. STR_Ascii2Ebcdic() : Converts a string from ASCII to EBCDIC. New
function. No code impact. The conversion table is fixed and it may not
perfectly correspond to the implementation of EBCDIC/ASCII that you face.
Use STR_SetConvTable() in conjunction with STR_ConvertA2B() and
STR_ConvertB2A() for tighter control.
15. STR_Ebcdic2Ascii() : Converts a string from EBCDIC to ASCII. New
function. No code impact. The conversion table is fixed and it may not
perfectly correspond to the implementation of EBCDIC/ASCII that you face.
Use STR_SetConvTable() in conjunction with STR_ConvertA2B() and
STR_ConvertB2A() for tighter control.
16. STR_SetConvTable() : sets the conversion table used by
STR_ConvertA2B() and STR_ConvertB2A() . New function. No code
impact.
17. STR_ConvertA2B() : Convert a character string according to a conversion
table set with and STR_SetConvTable() . New function. No code impact.
18. STR_ConvertA2B() : Convert a character string according to a
conversion table set with and STR_SetConvTable() . New function. No
code impact.
19. STR_Sort() : sorts a character string. New function. No code impact.
20. STR_SetCharConversion() : sets a single character conversion. New
21. DDA_Evaluate() did not evaluate memo fields correctly. That was a bug.
Function fixed. No code impact.
8.05 17 April 2003 1. NUM_int_min() : determines the minimum of an integer. New function.
No code impact.
2. NUM_int_max() : determines the maximum of an integer. New function.
No code impact.
3. NUM_long_min() : determines the minimum of a long. New function. No
code impact. Even though NUM_long_min() is a different function than
NUM_int_min() , they both return the same value.
4. NUM_long_max() : determines the maximum of a long. New function. No
code impact. Even though NUM_long_max() is a different function than
NUM_int_max() , they both return the same value.
5. NUM_radix() : reverse function of NUM_Base() . New function. No code
impact.
6. PRN_GetPrnData() : takes additional flags to obtain the following
information: printer attributes, printer priority, printer default priority,
printer start time, printer until time, printer status, printer job count,
printer average page per minute. New parameters. No code impact.
7. WIN_Select() : selects a given window an redirects the VFP output to it.
8. WIN_bottom() : the parameter of the function can either be the title of
the window, or its WHANDLE. New parameter. No code impact.
9. WIN_top() : the parameter of the function can either be the title of the
window, or its WHANDLE. New parameter. No code impact.
10. WIN_height() : the parameter of the function can either be the title of
the window, or its WHANDLE. New parameter. No code impact.
11. WIN_width() : the parameter of the function can either be the title of the
12. WIN_left() : the parameter of the function can either be the title of the
13. WIN_right() : the parameter of the function can either be the title of the
14. WIN_setPort() :Changes the user output window to be the specified
window. New function. No code impact.
15. WIN_getPort() :Returns the WHANDLE of the window that is currently
selected for user output. New function. No code impact.
16. FIL_wipe() : Wipes a file. New function. No code impact.
17. STR_hexa() : internal bug corrected. No code impact.

Change Control
18. ZIP_Compress() : compresses a set of files and put them in an archive
(ZIP, compatible with WinZIP/PKWare). New function. No code impact.
19. ZIP_Expand() : expands a set of files contained in an archive (ZIP,
compatible with WinZIP/PKWare). New function. No code impact.
20. ZIP_SetCallback() : sets a callback function that is executed from
within compression/expansion routines (ZIP_Compress() and
ZIP_Expand() ). New function. No code impact.
21. HTTP_SetCallback() : sets a callback function that is executed from
within the HTTP_GetURL*() functions. New function. No code impact.
22. SYS_ExitWindows () : a bug was preventing the function to operate in
normal conditions if the security privileges were not granted. This has been
corrected to grant the missing privileges in the function itself. impact.
23. SYS_WinExecEx() : identical in behavior as SYS_WinExec() but this
time the function returns the resulting Process Identifier (PID). New
24. The LZE_*() functions have been removed from the library because they
are now obsolete (ZIP_*() ). Code impact.
8.06 20 February 2004 1. SHE_GetIconCount() : get the number of icons in an executable or in a
DLL. New function. No code impact.
2. WIN_GetIcon() : extracts an icon from an executable or DLL file. New
3. WIN_DrawIcon() : draws an icon. New function. No code impact.
4. WIN_DestroyIcon() : destroys an icon (returned by WIN_GetIcon() ).
5. STR_KeepVowels() : Keeps only the vowels of a string. New function. No
code impact.
6. STR_KeepConsonants() : Keeps only the consonants of a string. New
7. GDI_ScreenToClient() : Converts the screen coordinates of a specified
point on the screen to client-area coordinates. New function. No code
impact.
8. GDI_ClientToScreen() : Converts the client-area coordinates of a
specified point to screen coordinates. New function. No code impact.
9. NUM_Between() : Determines whether a number is between 2 others.
10. GDI_Line() : This function supersedes the GRA_Line() function. New
function. Code impact if you used GRA_Line() .
11. WHOIS_whois() : Documentation corrected/updated. No code impact.
12. PRN_Source() : Marked as outdated. Superseded by
PRN_SetPrnData() . Potential code impact.
13. PRN_SetPrnData() : Old function that was NOT documented. The
function is now documented as it should be.
14. FIL_Owner() : Old function completed: retrieves the name of the owner
of a file. Possible code impact.
15. FIL_LastError() : Retrieves the last error that occurred in the file
functions. New function. No code impact.
8.07 27 February 2004 1. SCR_EnumDisplaySettings() : Enumerate the display settings of the

current display device. New function. No code impact.
2. SCR_GetDMMember() : Retrieves a member of the internal DEVMODE
structure that is populated after a call to
SCR_EnumDisplaySettings() . New function. No code impact.
3. SCR_LastError() : Determines the last error that occurred within the
SCR_*() functions. New function. No code impact.
4. SCR_ResetDisplaySettings() : Returns to the default display mode.
Use in combination with SCR_LastError() to obtain more information
about the last operation. New function. No code impact.
5. MOU_isLeftMouseDown() : Is the left mouse button down? New
function. No code impact. Useful when you cannot rely on MouseDown()
or MouseUp() events.
6. MOU_isLeftMouseUp() : Is the left mouse button up? New function. No
code impact. Useful when you cannot rely on MouseDown() or
MouseUp() events.
7. MOU_isMiddleMouseDown() : Is the middle mouse button down? New

Change Control
8. MOU_isMiddleMouseUp() : Is the middle mouse button up? New
9. MOU_isRightMouseDown() : Is the right mouse button down? New
10. MOU_isRightMouseUp() : Is the right mouse button up? New function.
No code impact. Useful when you cannot rely on MouseDown() or
MouseUp() events.
11. MTH_PtBelongsToLine() : New function. No code impact.
12. FIL_Get() : An additional example has been created in the
documentation. Easy to pick this example in your real code.
13. MNU_Create() : Support for grayed out options and checked options. No
code impact.
14. MNU_Make() : Creates an internal memory structure to create nice context
menus. New function. No code impact.
15. MNU_Destroy() : Destroys an internal menu memory structure created
with MNU_Make() . New function. No code impact.
16. MNU_AddItem() : Adds an item to a menu created with MNU_Make() .
17. MNU_AddMenu() : Adds a submenu to a menu created with MNU_Make() .
18. MNU_Play() : Plays a menu created with MNU_Make() . and constructed
thanks to calls to MNU_AddItem() and MNU_AddMenu() . New function.
No code impact.
19. ZIP_SetCallback() : even though the function was once reported as
being included in the library, it was not set in the final version. Our
apologies for this problem. Now the function is really active. What's more,
it is now even called for the new ZIP_List() function.
20. ZIP_List() :List all entries found in an archive file (ZIP file). When used
in combination with the ZIP_SetCallback() function, it is easy to
retrieve all files/directories. The function comes with a real example. New
8.08 06 March 2004 1. MEM_Compress() : Compresses a string. New function. No code impact.
This function has been entered into the ZIP category as it uses the
internals of the ZIP functions.
2. MEM_Decompress() : Decompresses a string that was once compressed
with MEM_Compress() . New function. No code impact. This function has
been entered into the ZIP category as it uses the internals of the ZIP
functions.
3. ZIP_SetSubdirs() : Determines whether ZIP_Compress() must treat
subdirectories or not. By default, ZIP_compress() does NOT compress
subdirectories. New function. No code impact.
4. ZIP_Compress() : Additional parameter supported to add files to an
existing archive. Also, now ZIP_Compress() can compress subdirectories
(setting is controlled via ZIP_SetSubdirs() ). No code impact.
5. NET_GetComputerName() : Two new aliases were created for the
function: NET_ComputerName() and ComputerName() . Possible code
impact.
6. FIL_Canonicalize() : Rewritten. No code impact. New aliases:
SHE_PathCanonicalize() ,FIL_PathCanonicalize() . The function
has been rewritten to be re-used internally in many file oriented functions.
7. FIL_Common() : Rewritten. No code impact. New aliases:
SHE_PathCommonPrefix() , FIL_PathCommonPrefix() .The function
has been rewritten to be re-used internally in many file oriented functions.
8. FIL_IsUNC() : Rewritten. No code impact. New aliases:
SHE_PathIsUNC() , FIL_PathIsUNC() .The function has been rewritten
to be re-used internally in many file oriented functions.
9. SHE_PathIsUNCServer() : Determines if a string is a valid UNC for a
server path only. New function. No code impact.
10. SHE_PathIsUNCServerShare() : Determines if a string is a valid UNC
share path, \\server\share. New function. No code impact.
11. SHE_PathAddBackslash() : Adds a backslash to a path if needed
(similar to ADDBS() ). New function. No code impact. The function has
been added to be re-used internally in some file oriented functions. The
function has also a companion function to remove backslashes:
SHE_PathRemoveBackslash() .

Change Control
12. SHE_PathRemoveBackslash() : Removes the ending backslash of a
path if needed. New function. No code impact. This function is the
companion function of SHE_PathAddBackslash() .
13. SHE_PathIsURL() : Determines if a string conforms to a valid URL
format. New function. No code impact. The function has several aliases:
FIL_PathIsURL() , FIL_IsURL() , HTTP_IsURL() .
14. SHE_PathIsRoot() : Parses a path to determine if it is a directory root.
15. SHE_PathIsRelative() : Searches a path and determines if it is relative
or not. New function. No code impact.
16. IP_Ping() : Corrections in the way errors are reported via
IP_LastError() . No code impact.
17. NET_InternetTime() : Corrections in the way errors are reported via
NET_LastError() . No code impact.
8.09 31 July 2004 1. DAT_NumberOfDays() : Has a new alias: DAT_DaysInMonth() .
Potential code impact if you have already defined a function with that
name.
2. ZIP_LastError() , COM_LastError() , EVE_LastError() ,
HTTP_LastError() , IP_LastError() , LOG_LastError() ,
MAPI_LastError() , MSG_LastError() , NET_LastError() ,
NOT_LastError() , NTE_LastError() , PRN_LastError() ,
SCR_LastError() , SHE_LastError() , SYS_LastError() : bug
solved. The functions performed a reset of the last operation BEFORE
returning its value to the caller. This led to returning "The operation
completed successfully" ALWAYS. It is no longer the case. No code
impact.
3. MEM_Decompress() : bug fixed. When the function tried to calculate the
probable length of the output buffer, it used a too simple algorithm. The
algorithm has been adapted. No code impact.
4. FIL_GetStdin() : Reads a number of characters from the standard
input (stdin). New function. No code impact.
5. FIL_PutStdout() : Outputs a string to the standard output device
(stdout). New function. No code impact.
6. ZIP_Compress() : the callback evaluation has been corrected. No code
impact.
7. ZIP_List() : the number of resources found in an archive did return 1
less than the actual number of resources. The problem has been corrected.
No code impact.
8.10 6 September 2004 1. HTTP_DecodeQueryString() : Decodes the query string sent as part of
a URL. New function. No code impact. See also HTTP_DecodeURL() and
HTTP_EncodeURL() .
2. STR_Find() : The function is now documented. It was present in the
library but it was never documented. Sorry for that. No code impact.
3. STR_FindBackward() : The function is now documented. It was present
in the library but it was never documented. Sorry for that. No code impact.
4. WIN_SetParent() : Changes the parent window of the specified child
window. New function. No code impact.
5. NUM_IsPrime() : Determines if a number is a prime number or not. New
6. NUM_GetPrevPrime() : Returns the previous prime number of a number.
7. NUM_GetNextPrime() : Returns the next prime number of a number.
8. HTTP_URLEncode() : Encodes a URL. New function. No code impact.
9. HTTP_URLDecode() : Decodes a URL. New function. No code impact.

List of Dependencies
With version 7.88 we have introduced a List of Dependencies to ease the process of tracking down the files that can
cause FOCUS.FLL not to load properly.
Version Dependencies
7.88 1. ADVAPI32.DLL 4.80.0.1675
2. COMCTL32.DLL 5.81.3105.105
3. COMDLG32.DLL 4.72.3110.2
4. FOCUS.FLL 7.88.0.0
5. GDI32.DLL 4.10.10.1998
6. KERNEL.DLL 0.0.0.0
7. KERNEL32.DLL 4.10.0.1998
8. LZ32.DLL 4.10.0.1998
9. MPR.DLL 4.10.0.1998
10. MSVCRT.DLL 6.0.8797.0
11. NETAPI32.DLL 4.10.0.1998
12. NETBIOS.DLL 0.0.0.0
13. OLE32.DLL 4.71.2612.0
14. SHELL32.DLL 4.72.3110.6
15. SHLWAPI.DLL 5.0.3105.105
16. USER32.DLL 4.10.0.1998
17. VERSION.DLL 4.10.0.1998
18. WININET.DLL 5.0.3105.105
19. WINMM.DLL 4.3.0.1998
20. WINSPOOL.DRV 4.10.0.1998
21. WS2HELP.DLL 4.10.0.1998
22. WS2_32.DLL 4.10.0.1998
7.89 1. ADVAPI32.DLL 4.80.0.1675

2. COMCTL32.DLL 5.81.3105.105
3. COMDLG32.DLL 4.72.3110.2
4. FOCUS.FLL 7.88.0.0
5. GDI32.DLL 4.10.10.1998
7. KERNEL32.DLL 4.10.0.1998
8. LZ32.DLL 4.10.0.1998
9. MPR.DLL 4.10.0.1998
10. MSVCRT.DLL 6.0.8797.0
11. NETAPI32.DLL 4.10.0.1998
13. OLE32.DLL 4.71.2612.0
14. SHELL32.DLL 4.72.3110.6
15. SHLWAPI.DLL 5.0.3105.105
16. USER32.DLL 4.10.0.1998
17. VERSION.DLL 4.10.0.1998
18. WININET.DLL 5.0.3105.105
19. WINMM.DLL 4.3.0.1998
20. WINSPOOL.DRV 4.10.0.1998
21. WS2HELP.DLL 4.10.0.1998
22. WS2_32.DLL 4.10.0.1998
7.90 1. ADVAPI32.DLL 4.80.0.1675

2. COMCTL32.DLL 5.81.3105.105
3. COMDLG32.DLL 4.72.3110.2
4. FOCUS.FLL 7.88.0.0
5. GDI32.DLL 4.10.10.1998
7. KERNEL32.DLL 4.10.0.1998
8. LZ32.DLL 4.10.0.1998
9. MPR.DLL 4.10.0.1998
10. MSVCRT.DLL 6.0.8797.0
11. NETAPI32.DLL 4.10.0.1998
13. OLE32.DLL 4.71.2612.0
14. SHELL32.DLL 4.72.3110.6
15. SHLWAPI.DLL 5.0.3105.105
16. USER32.DLL 4.10.0.1998
List of Dependencies
17. VERSION.DLL 4.10.0.1998
18. WININET.DLL 5.0.3105.105
19. WINMM.DLL 4.3.0.1998
20. WINSPOOL.DRV 4.10.0.1998
21. WS2HELP.DLL 4.10.0.1998
22. WS2_32.DLL 4.10.0.1998
After Unchanged since version 7.90

Array Functions
Array Functions

Array Functions
ARR_average() : Returns the average of all numeric elements

contained in an array.
Syntax
ARR_average( @aArray )  nAverage
Parameters
aArray the array to process. MUST BE PASSED BY REFERENCE
Returns
nAverage average value. Only the numeric values contained in aArray are taken into account.
Example
LOCAL ARRAY aArray[2,3]
aArray[1,1] = 1
aArray[1,2] = 45
aArray[1,3] = 3
aArray[2,1] = 113
aArray[2,2] = 5
aArray[2,3] = 78
? ARR_average( @aArray ) && 40.8333
LOCAL ARRAY aArray[5]
aArray[1] = 2
aArray[2] = 10
aArray[3] = 8
aArray[4] = 7
aArray[5] = 8
? ARR_average( @aArray ) && 7,000 ... same as ...

? (aArray[1] + aArray[2] + aArray[3] + aArray[4] + aArray[5] )/ALEN(aArray)
ARR_Create() : Creates an array of given dimensions.

Remark
With ARR_create() you can create arrays with 0 elements.
Syntax
ARR_Create( szArray,iRows,iCols[,iScope] )  lSuccess
Parameters
szArray the name of the variable that will hold the array. Please notice that if szArray is already an
existing variable, ARR_create() will fail.
iRows the number of rows for a two-dimensional array, or number of elements for a one-dimensional
array (in that case, iCols is set to 0).
iCols the number of columns for two-dimensional arrays. In case of one-dimensional arrays, this
parameter must be set to 0.
iScope 0 for PUBLIC variables; 1 for PRIVATE variables. This parameter is optional. By default,
ARR_create() uses PRIVATE variables.
Returns
lSuccess .T. if the array was created successfully; .F. if not.

Array Functions
Please notice that if szArray is the name of an existing variable, ARR_create() will
fail.
Example
IF ( ARR_create( "aArray",4,2 ) )
? "aArray has been created as an array of 4 rows,2 columns"
ENDIF
&& Creation of an array with 0 elements

? ARR_create( "aNoElemArray",0,0 ) && .T.
? ARR_IsArray( @aNoElemArray ) && .T.
? ALEN( aNoElemArray ) && 0
RELEASE aNoElemArray
&& Creation of an array with 0 rows and 4 columns

? ARR_create( "aNoElemArray",0,4 ) && .T.
? ARR_IsArray( @aNoElemArray ) && .T.
? ALEN( aNoElemArray ) && 0
? ALEN( aNoElemArray,1 ) && 0
? ALEN( aNoElemArray,2 ) && 4
ARR_Dimensions() : Determines the dimensions of an array

(rows and cols).
Syntax
ARR_Dimensions( @aArray,@iRows,@iCols )  lSuccess
Parameters
aArray the array to process. MUST BE PASSED BY REFERENCE.
iRows the variable that will receive the number of rows contained in the array. MUST BE PASSED BY
REFERENCE. If aArray is one-dimensional, this variable will receive the number of elements
contained in the array and iCols will be fetched with 0.
iCols the variable that will receive the number of cols contained in the array. MUST BE PASSED BY
REFERENCE. If aArray is two-dimensional, this variable will receive the number of columns
contained in the array; otherwise this variable is set to 0.
Returns
lSuccess .T. if the function was successful; .F. if not (aArray is not an array for example).
Example
LOCAL iRows,iCols
iRows = 0
iCols = 0
IF ( ARR_Dimensions( @aArray,@iRows,@iCols ) )
? iRows && 4
? iCols && 8
ENDIF
LOCAL ARRAY aArray[16]
IF ( ARR_Dimensions( @aArray,@iRows,@iCols ) )
? iRows && 16
? iCols && 0
ENDIF
RELEASE ALL
LOCAL iRows,iCols
LOCAL szVar
szVar = "Hello World"

iRows = 0

Array Functions
iCols = 0
IF ( ! ARR_Dimensions( @szVar,@iRows,@iCols ) )
? "szVar is probably not an array"
ENDIF
ARR_elements() : Total number of elements in an array.

Syntax
ARR_elements( @aArray )  nElements
Parameters
aArray the array to process. MUST BE PASSED BY REFERENCE.
Returns
nElements number of elements in the array (the array can be empty-none of its elements initialized). If
aArray is not passed by reference, the function returns –1. If aArray is not an array, the
function returns –1.
Example
LOCAL MyVar
LOCAL ARRAY aArray1[10,11]
LOCAL ARRAY aArray2[3]
? ARR_elements( aArray1 ) && -1 (because the array hasn't been passed by ref.)
? ARR_elements( @aArray1 ) && 110
MyVar = "Hello world"

? ARR_elements( MyVar ) && -1
? ARR_elements( @aArray2 ) && 3
ARR_columns() : Number of columns in an array.

Syntax
ARR_columns( @aArray )  nElements
Parameters
aArray the array to process.
Returns
nElements number of columns in the array (the array can be empty-none of its elements initialized). If
function returns –1. If aArray does not have a second subscript, the function returns 0.
Example
? ARR_columns( aArray1 ) && -1 (because the array hasn't been passed by ref.)
? ARR_columns( @aArray1 ) && 11
? ARR_rows( @aArray1 ) && 10

Array Functions
ARR_IsArray() : Determines if a variable is an array.
Syntax
ARR_IsArray( @var )  lSuccess
Parameters
var the variable to test. MUST BE PASSED BY REFERENCE.
Returns
lSuccess .T. if var is an array; .F. if not.
Example
LOCAL szVar
szVar = "Hello World"
? ARR_IsArray( @aArray ) && .T.

? ARR_IsArray( @szVar ) && .F.
ARR_max() : Returns the biggest numeric value of all elements

contained in an array.
Syntax
ARR_max( @aArray )  nValue
Parameters
Returns
nValue maximum value. Only the numeric values contained in aArray are taken into account.
Example
aArray[1,1] = 1
aArray[1,2] = 45
aArray[1,3] = 3
aArray[2,1] = 113
aArray[2,2] = 5
aArray[2,3] = 78
? ARR_max( @aArray ) && 113
ARR_min() : Returns the smallest numeric value of all

elements contained in an array.
Syntax
ARR_min( @aArray )  nValue
Parameters

Array Functions
Returns
nValue minimum value. Only the numeric values contained in aArray are taken into account.
Example
aArray[1,1] = 1
aArray[1,2] = 45
aArray[1,3] = 3
aArray[2,1] = 113
aArray[2,2] = 5
aArray[2,3] = 78
? ARR_min( @aArray ) && 1
ARR_rows() : Number of rows in an array.

Syntax
ARR_rows( @aArray )  nRows
Parameters
aArray the array to process.
Returns
nRows number of rows in the array (the array can be empty-none of its elements initialized). If
function returns –1.
Example
ARR_LastVersion() : Returns the file stamp of ARR_*()

functions.
Remark
This function helps the developer identifying the last version of a set of functions. Sometimes the global version
information of FOCUS.FLL (MIS_major() and MIS_minor() ) does not help tracking down the changes in a project.
Starting with version 6.0 of FOCUS.FLL , each source file has now an internal date and time stamp.
Syntax
ARR_LastVersion()  szLastVersion
Parameters
None.

Array Functions
Returns
szLastVersion string identifying the last version of the functions set. The string is similar to
"D:\Focus\6.0\array.c-Sat Jun 9 12:28:56 2001" .

BMP Functions
BMP Functions

BMP Functions
BMP_bits() : Number of bits per pixel.

Syntax
BMP_bits()  nBits
Parameters
None.
Returns
nBits number of bits per pixel.
Caution
Use BMP_height() , BMP_width() , BMP_colors() , and BMP_bits() only after a successful call to
BMP_header() .
BMP_colors() : Number of colors in the bitmap file.

Syntax
BMP_colors()  nColors
Parameters
None.
Returns
nColors number of colors.
Caution
BMP_header() .
BMP_header() : Reads a bitmap file header.

Alias
ReadBitmapHeader()
Syntax
BMP_header( szFile )  nError
Parameters
szFile bitmap file to read.
Returns
nError 0 if function is successful. <0 if error occurred.

BMP Functions
Value Description
-1 Cannot open BMP file
-2 Cannot read BMP file
-3 Not a BMP file
-4 Cannot load BMP file
-5 Not appropriate header size
Example
LOCAL szFile
szFile = "C:\MYOWN.BMP"
IF ( BMP_isbmp( szFile ) )
IF ( BMP_header( szFile ) == 0 )
? BMP_height(),BMP_width()
ENDIF
ENDIF
BMP_height() : Returns bitmap height.

Alias
GetBitmapHeight()
Syntax
BMP_height()  nHeight
Parameters
None.
Returns
nHeight bitmap height; -1 if not applicable.
Example
LOCAL szFile
ENDIF
ENDIF
Caution
BMP_header() .
BMP_isbmp() : Tests whether a file is a bitmap file.

Alias
IsBitmapFile()
Syntax
BMP_isbmp( szFile )  lIsBitmap

BMP Functions
Parameters
szFile file to test.
Returns
lIsBitmap .T. if file is a bitmap file, .F. otherwise.
Example
LOCAL szFile
ENDIF
ENDIF
BMP_LastVersion() : Returns the file stamp of BMP functions.

Remark
Syntax
BMP_LastVersion()  szLastVersion
Parameters
None.
Returns
szLastVersion if a string identifying the last version of the BMP functions. The string is similar to
"C:\Focus\5.0\BMP.C-Mon Oct 19 15:55:22 1998" .
BMP_width() : Returns bitmap width.

Alias
GetBitmapWidth()
Syntax
BMP_width()  nWidth
Parameters
None.
Returns
nWidth bitmap width; -1 if not applicable.

BMP Functions
Example
LOCAL szFile
ENDIF
ENDIF
Caution
BMP_header() .

CD Functions
CD Functions

CD Functions
Function Synopsis
CD functions are specialized built-in services of FOCUS.FLL which allow the developer to control a CD player.
CD functions are using MCI functions to control the CD player. Most of the time, FOCUS.FLL is internally using the
mciSendString() function which uses MCI commands.
How to use CD’s functions?
Prior to using any function you should make sure a CD player is attached to the PC. You can use CD_iscd() function
to determine whether a CD player is attached to the system.
After checking, you must observe the following rules:
1. Open the CD device (CD_open() )
2. Issue all functions you want to use
3. Close the CD device when you no longer need it (you do not need to close the device necessarily).
Windows Control Panel
For the CD functions to work properly, you must ensure that a CD driver has been installed in the driver section of the
Control Panel.
CD player device name
All CD functions are directed to the FWCD device that is the alias the CD_open() function gave to the CDAUDIO
device. By default, you should use this alias (FWCD) if you desire to obtain tighter control on the device. This is also
the name you need to use in the CD_command() function.

CD Functions
CD_bayope() : Opens the door and ejects CD media (if

possible).
Syntax
CD_bayope()  .T.
Parameters
None.
Returns
.T. the function always returns .T..
CD_bayclo() : Retracts the tray and closes the door bay (if
possible).
Syntax
CD_bayclo()  .T.
Parameters
None.
Returns
CD_caneje() : Can CD audio device eject the media?

Syntax
CD_caneje()  lSuccess
Parameters
None.
Returns
lSuccess .T. if device can eject the disc tray; otherwise it returns .F..
CD_canpla() : Can CD audio device play the media?

Syntax
CD_canpla()  lSuccess
Parameters
None.

CD Functions
Returns
lSuccess .T. if media can be played; otherwise it returns .F..
CD_close() : Closes CD device.

Syntax
CD_close()  .T.
Parameters
None.
Returns
CD_command() : Sends a MCI command string to the CD

device open with CD_open().
Syntax
CD_command( szString )  .T.
Parameters
szString command to be sent to the CD player.
Returns
Example
&& FWCD is the alias that was given to the CDAUDIO.
CD_command( "play FWCD from 2 to 6" )
CD_curpos() : Returns the current position.

Syntax
CD_curpos()  szPosition
Parameters
None.
Returns
szPosition position in TMSF format (track, minute, second, frame).
CD_curtra() : Returns the current track.

Syntax
CD_curtra()  szTrack

CD Functions
Parameters
None.
Returns
szTrack returns the current track number as a string.
CD_end() : Moves to the end of audio data on the disc.

Syntax
CD_end()  .T.
Parameters
None.
Returns
CD_home() : Moves to the start of audio data on the disc.

Syntax
CD_home()  .T.
Parameters
None.
Returns
CD_iscd() : Is a CD-ROM attached to the computer?

Syntax
CD_iscd()  lCDAttached
Parameters
None.
Returns
lCDAttached .T. if a CD is attached to computer; .F. otherwise.

CD Functions
CD_LastError() : Determines the last error that occurred within
the CD_*() functions.
Alias
In fact, the CD_*() functions are implemented in the MCI.C source file because it belongs to this section. The same
goes for VID_*() functions. Therefore, CD_LastError() is mapped to MCI_LastError() . The following functions
are all synonyms :
CD_GetLastError(), CD_GetLastError(), VID_LastError(), VID_GetLastError(), MCI_LastError(),
MCI_GetLastError())
Syntax
CD_LastError()  szLastError
Parameters
None.
Returns
szLastError string describing the last error that occurred using the CD_*() functions.
CD_LastVersion() : Returns the file stamp of CD_*() functions.

Remark
Syntax
CD_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\MCI.C-Mon Oct 19 15:55:22 1998" .
CD_loff() : Disables output to the left audio channel.

Alias
CD_LeftOff()
Syntax
CD_loff()  .T.
Parameters
None.

CD Functions
Returns
CD_lon() : Enables output to the left audio channel.

Alias
CD_LeftOn()
Syntax
CD_lon()  .T.
Parameters
None.
Returns
CD_MediaPresent() : Returns .T. if a disc is inserted in the

drive.
Syntax
CD_MediaPresent()  lMediaIsThere
Parameters
None.
Returns
lMediaIsThere .T. if a disc is inserted in the disc tray and the door is closed; .F. if not.
CD_mode() : Returns a value indicating the current mode of

the device.
Syntax
CD_mode()  szStatus
Parameters
None.
Returns
szStatus current device status.
Not ready
Open
Paused
Playing
Seeking
Stopped

CD Functions
CD_msf() : Sets the current time format to MSF (minutes,
seconds, frames).
Syntax
CD_msf()  .T.
Parameters
None.
Returns
CD_ms() : Sets the current time format to MS (milliseconds).

Syntax
CD_ms()  .T.
Parameters
None.
Returns
CD_off() : Disables audio output (mute).

Alias
CD_mute()
Syntax
CD_off()  .T.
Parameters
None.
Returns
CD_on() : Enables audio output (unmute).

Alias
CD_unmute()
Syntax
CD_on()  .T.

CD Functions
Parameters
None.
Returns
CD_open() : Opens CD device.

Special
Prior to issuing any CD function (except CD_iscd() ), you need to make a call to CD_open() to ensure that the
CDAUDIO device will be accessible. The CDAUDIO device is open assuming the TMSF format. It is given the CD alias
("open CDAUDIO alias FWCD" ).
Syntax
CD_open()  lSuccess
Parameters
None.
Returns
lSuccess was the attempt to open the CDAUDIO device successful or not?
CD_pause() : Pauses playing.

Syntax
CD_pause()  .T.
Parameters
None.
Returns
CD_play() : Plays CD tracks.

Syntax
CD_play()  .T.
Parameters
None.
Returns

CD Functions
CD_ready() : Determines whether the CD is ready.
Syntax
CD_ready()  lSuccess
Parameters
None.
Returns
lSuccess .T. if CD ready to play; .F. if not.
CD_resume() : Resumes playback.

Syntax
CD_resume()  .T.
Parameters
None.
Returns
CD_roff() : Disables output to the right audio channel.

Alias
CD_RightOff()
Syntax
CD_roff()  .T.
Parameters
None.
Returns
CD_ron() : Enables output to the right audio channel.

Alias
CD_RightOn()
Syntax
CD_ron()  .T.
Parameters
None.

CD Functions
Returns
CD_seek() : Moves to the specified position.

Special
CD_seek() moves to given position according to the time format. At start-up, the CDAUDIO device is opened in the
TMSF format (Track, minutes, seconds, frames). This setting will make CD_seek() to operate on tracks. If the time
format is later set up to the MSF format, CD_seek() will then perform a sequential seek on minutes.
Syntax
CD_seek( szObject )  .T.
Parameters
szObject object to move to. szObject is depending on the time format.
Returns
CD_start() : Positions the disc at the starting position.

Syntax
CD_start()  lSuccess
Parameters
None.
Returns
lSuccess .T.. if the function is successful; .F. otherwise.
CD_stop() : Stops playback.

Syntax
CD_stop()  lSuccess
Parameters
None.
Returns
CD_time() : Returns the current time format.

Syntax
CD_time()  szFormat

CD Functions
Parameters
None.
Returns
szFormat current time format. Normally, the TMSF format is used all in all the CD_*() functions but this
default may be change via external services.
CD_tmsf() : Sets the current time format to TMSF.

Syntax
CD_tmsf()  .T.
Parameters
None.
Returns
CD_totlen() : Returns the total length of disc.

Syntax
CD_totlen()  szTime
Parameters
None.
Returns
szTime total length of the disc.
CD_tottra() : Returns the number of tracks on the disc.

Syntax
CD_tottra()  szTrackCount
Parameters
None.
Returns
szTrackCount number of tracks (as a string).
CD_tralen() : Returns the length of a given track.

Syntax
CD_tralen( szTrackNo )  szLength

CD Functions
Parameters
szTrackNo track number (as string) of which to obtain length.
Returns
szLength length of given track.
CD_trapos() : Returns the starting position of a given track.

Syntax
CD_trapos( szTrackNo )  szPosition
Parameters
szTrackNo given track.
Returns
szPosition position at which the given track starts.

Clipboard Functions
Clipboard Functions

Clipboard Functions
CLP_CountFormats() : Counts the number of different data

formats available in the clipboard.
Alias
CountClipboardFormats()
Syntax
CLP_CountFormats()  nFormatCount
Parameters
None.
Returns
nFormatCount number of data formats available in the clipboard.
Example
IF ( CLP_CountFormats() == 0 )
? "No data available in the clipboard"
ENDIF
CLP_empty() : Clears the Windows clipboard.

Syntax
CLP_empty()  lSuccess
Parameters
None.
Returns
lSuccess .T. if operation was successful; .F. otherwise.
CLP_GetText() : Gets text from Windows clipboard.

Remark
The CLP_GetText() function is similar to query the _CLIPTEXT internal variable of Visual FoxPro.
Syntax
CLP_GetText()  szText
Parameters
None.
Returns
szText text that was stored into the Windows clipboard.

Clipboard Functions
CLP_IsFormatAvailable() : Determines whether the clipboard
contains data in the specified format.
Alias
IsClipboardFormatAvailable()
Syntax
CLP_IsFormatAvailable( nFormat )  lAvailable
Parameters
nFormat specifies a standard or registered clipboard format.
CF_TEXT 1 Text format. Each line ends with a carriage return/linefeed (CR-
LF) combination. A null character signals the end of the data. Use
this format for ANSI text.
CF_BITMAP 2 A handle to a bitmap (HBITMAP).
CF_METAFILEPICT 3 Handle of a metafile picture format as defined by the
METAFILEPICT structure.
CF_SYLK 4 Microsoft Symbolic Link (SYLK) format.
CF_DIF 5 Software Arts' Data Interchange Format.
CF_TIFF 6 Tagged-image file format.
CF_OEMTEXT 7
CF_DIB 8 A memory object containing a BITMAPINFO structure followed
by the bitmap bits.
CF_PALETTE 9 When displaying clipboard data, Windows clipboard always uses
as its current palette any object on the clipboard that is in the
CF_PALETTE format
CF_PENDATA 10 Data for the pen extensions to the Microsoft Windows for Pen
Computing.
CF_RIFF 11 Represents audio data more complex than can be represented in
a CF_WAVE standard wave format.
CF_WAVE 12 Represents audio data in one of the standard wave formats, such
as 11 kHz or 22 kHz pulse code modulation (PCM).
CF_UNICODETEXT 13 Windows NT only: Unicode text format. Each line ends with a
carriage return/linefeed (CR-LF) combination. A null character
signals the end of the data.
CF_ENHMETAFILE 14 A handle of an enhanced metafile (HENHMETAFILE).
CF_HDROP 15 A handle of type HDROP that identifies a list of files. An
application can retrieve information about the files by passing the
handle to the DragQueryFile functions.
CF_LOCALE 16 The data is a handle to the locale identifier associated with text
in the clipboard. When you close the clipboard, if it contains
CF_TEXT data but no CF_LOCALE data, the system automatically
sets the CF_LOCALE format to the current input locale. You can
use the CF_LOCALE format to associate a different locale with the
clipboard text. An application that pastes text from the clipboard
can retrieve this format to determine which character set was
used to generate the text. Note that the clipboard does not
support plain text in multiple character sets. To achieve this, use
a formatted text data type such as RTF instead. Windows NT:
The system uses the code page associated with CF_LOCALE to
implicitly convert from CF_TEXT to CF_UNICODETEXT. Therefore,
the correct code page table is used for the conversion.
Returns
lAvailable .T. if the specified format is available; .F. otherwise.

Clipboard Functions
CLP_LastVersion() : Returns the file stamp of CLP functions.
Remark
Syntax
CLP_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\CLP.C-Mon Oct 19 15:55:22 1998" .
CLP_SetText() : sets text into the Windows clipboard.

Remark
The CLP_SetText() function is similar to assign the _CLIPTEXT internal variable of Visual FoxPro.
Syntax
CLP_SetText( szText )  lSuccess
Parameters
szText text to store into the Windows clipboard.
Returns
lSuccess .T. successful operation; .F. if not.

COM Functions
COM Functions

COM Functions
Functions Synopsis
We are currently reworking the COM functions. They were once available in FOCUS.FLL for FoxPro 2.6 but were
removed in FOCUS.FLL for Visual FoxPro.
Please do not start working with these functions yet as we're not sure about their final implementation.
This is actually work in progress!
Working With COM
The most critical phase in serial communications programming is configuring the port settings. Usually this is
performed with a DCB (Device Control Block) structure. Initializing the DCB structure is a common problem and very
often, when the serial communication functions do not produce the expected results, the DCB structure comes in good
place to take a look at. With FOCUS.FLL COM functions though, the settings of the DCB structure are set
automatically for the sake of your convenience. Should the automatic settings not fit your needs, then please be aware
that FOCUS.FLL provides additional mechanisms to tighter control them.
A call to the CreateFile() Win32 API function opens a serial port with default port settings. Very often, the
application needs to change the defaults, something performed via a call to the SetCommState() function.
The SetCommState() function uses a DCB structure that you can first populate with the current status. Use the
GetCommState() function to retrieve the default settings and use the SetCommState() function to set new port
settings.
When the correct port settings are set, you're ready to read and write to the COM port.
Working With FOCUS.FLL COM Functions
FOCUS.FLL works the same way while providing a higher level of abstraction. Instead of using the CreateFile()
Win32 API function, you use the COM_open() function that opens the port for read and write operations. At this
stage, you can already decide to read and/or write from/to COM ports … if the default settings match your
requirements. Should these settings not be satisfactory, then use the COM_SetCommState() function to use your
own settings.
Once you're done with the port, you simply close it using the COM_close() function.
Working With Handles
FOCUS.FLL COM functions use handles similarly to file functions. When a COM port is opened via the COM_Open()
function it is identified by a COM handle. In all subsequent COM calls, the handle of the COM port must be passed as a
key parameter to the function.
LOCAL nCOMHandle
nCOMHandle = COM_open( "COM1" )
IF ( nCOMHandle != -1 )
? "The COM port has been successfully opened for Read and Write operations"
COM_close( nCOMHandle )
ELSE
? "Cannot open COM1 (" + COM_LastError() + ")"
ENDIF
THIS PART OF THE DOCUMENTATION IS STILL UNDER CONSTRUCTION
Examples

COM Functions
COM_BuildCommDCB() : Fills the internal DCB structure of one of the COM handles of FOCUS with the
specified values.
COM_Close() : Closes a serial communication.
COM_LastError() : Returns an error string indicating the nature of the last error encountered.
COM_LastVersion() : Returns the file stamp of COM functions.
COM_MaxHandle() : Returns the highest possible COM handle.
COM_MinHandle() : Returns the lowest possible COM handle.
COM_HandlesCount() : Returns the maximum number of COM handles.
COM_HandlesFree() : Returns the number of free COM handles.
{ "COM_SETCOMMSTATE" ,(FPFI) FW_COM_SetCommState ,1,"C" },
{ "COM_OPEN" ,(FPFI) FW_COM_open ,3,"C,I,I" },
{ "COM_READ" ,(FPFI) FW_COM_read ,3,"I,R,I" },
{ "COM_SETPORTSETTINGS" ,(FPFI) FW_COM_SetPortSettings ,1,"C" },
{ "COM_FLASHDTR" ,(FPFI) FW_COM_FlashDTR ,0,"" },
{ "COM_WRITE" ,(FPFI) FW_COM_write ,3,"I,C,I" },

COM Functions
COM_BuildCommDCB() : Fills the internal DCB structure of

one of the COM handles of FOCUS with the specified
values.
Syntax
COM_BuildCommDCB( nCOMHandle,szControlString )  lSuccess
Parameters
nCOMHandle handle to a communication device. This handle is typically returned by the COM_open()
function of FOCUS.FLL .
szControlString string that specifies device-control information. The string must have the same form as the
mode command's command-line arguments. For example, the following string specifies a baud
rate of 1200, no parity, 8 data bits, and 1 stop bit:
"baud=1200 parity=N data=8 stop"
Returns
lSuccess .T. if the DCB structure is filled successfully; .F. otherwise.
COM_close() : to be continued.
Syntax
Parameters
?? ????.
Returns
?? ????.
COM_LastVersion() : Returns the file stamp of COM functions.

Remark
Syntax
COM_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\COM.C-Mon Oct 19 15:55:22 1998" .

COM Functions
COM_open() : to be continued.
Syntax
Parameters
?? ????.
Returns
?? ????.
COM_read() : to be continued.
Syntax
Parameters
?? ????.
Returns
?? ????.
COM_SetCommState() : Configures a communications device

according to the specifications found in the FOCUS
internal DCB.
Remark
There is only one DCB internal structure in FOCUS.FLL COM functions at the present time. This structure is used in all
subsequent calls to COM functions of FOCUS.FLL . Please notice that the COM_SetCommState() reinitializes all
hardware and control settings, but it does not empty output or input queues.
Syntax
COM_LastVersion()  szLastVersion
Parameters
?? ????.
Returns
?? ????.
COM_write() : to be continued.
Syntax

COM Functions
Parameters
?? ????.
Returns
?? ????.

Cursor Functions
Cursors Functions

Cursor Functions
CUR_LastVersion() : Returns the file stamp of CUR functions.

Remark
Syntax
CUR_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\CURSOR.C-Mon Oct 19 15:55:22 1998" .
CUR_load() : Creates a cursor based on data contained in a

file.
Remark
Although perfectly operational, the CUR_Load() function of FOCUS.FLL suffers from VFP default cursor handling.
Usually, setting up the cursor thanks to CUR_Load() seems to have no effect at all. This is because VFP resets the
cursor to what it finds appropriate based on the context of the program.
The file is specified by its name or by a system cursor identifier. The function returns a handle to the newly created
cursor. Files containing cursor data may be in either cursor (.CUR ) or animated cursor (.ANI) format.
Syntax
CUR_Load( szCursorFile )  lSuccess
Parameters
szCursorFile indicates the source of the file data to be used to create the cursor. The data in the file must be
in either .CUR or .ANI format.
Returns
lSuccess .T. if the cursor file is loaded successfully; .F. otherwise.
Example
CUR_Load( "C:\WINDOWS\CURSORS\MYHAND.CUR" )

Date Functions
Date Functions

Date Functions
DAT_bom() : Beginning of the month.

Syntax
DAT_bom( dDate )  dBOM
Parameters
dDate date to convert.
Returns
dBOM date corresponding to the beginning of the month.
Example
? DAT_bom( {31/12/1998} ) && 01/12/1998
DAT_boy() : Beginning of the year.

Syntax
DAT_boy( dDate )  dBOY
Parameters
Returns
dBOY date corresponding to the beginning of the year.
Example
? DAT_boy( {31/12/1998} ) && 01/01/1998
DAT_ctot() : Character to datetime string.

Syntax
DAT_ctot( szDateTime )  tDateTime
Parameters
szDateTime datetime expression to convert. The format of the parameter is depending on the current date
setting (mm/dd/year hh:mm:ss).
Returns
tDateTime datetime corresponding to szDateTime .
Example
SET DATE TO AMERICAN
? DAT_ctot( "05/31/1999 18:15:30" ) && {05/31/1999 18:15:30}
SET DATE TO BRITISH
? DAT_ctot( "31/05/1999 18:15:30" ) && {31/05/1999 18:15:30}

Date Functions
DAT_DateTime() : Current date and time (char YYYY-MM-DD
hh:mm:ss).
Alias
STR_DateTime()
Syntax
DAT_DateTime()  szDateTime
Parameters
None.
Returns
szDateTime 20 characters string in the YYYY-MM-DD hh:mm:ss format (there are 2 spaces between the
date and the time).
Example
LOCAL szAlmostUnique
&& Creates an almost unique filename

szAlmostUnique = STR_dionly( DAT_DateTime() ) && "19990420081219"
DAT_day() : Returns the numeric day-of-the-month for a given

date.
Syntax
DAT_day( dDate )  nDay
Parameters
dDate date to obtain the day of.
Returns
nDay day (from 1 to 31).
Example
? DAT_doy( {^1998-12-31} ) && 31
DAT_doy() : Returns the day-of-the-year of a given date.

Syntax
DAT_doy( dDate )  nDay
Parameters
dDate date to obtain the day of year of.
Returns
nDay day (from 1 to 366).

Date Functions
Example
? DAT_doy( {^1998-12-31} ) && 365
DAT_eom() : End of the month.

Syntax
DAT_eom( dDate )  dEOM
Parameters
Returns
dEOM date corresponding to the end of the month. Leap years are supported.
Example
? DAT_eom( {01/02/2000} ) && 29/02/2000
DAT_eoy() : End of the year.

Syntax
DAT_eoy( dDate )  dEOY
Parameters
Returns
dEOY date corresponding to the end of the year.
Example
? DAT_eoy( {01/01/1998} ) && 31/12/1998
DAT_Easter() : Determines the exact date of Easter.

Syntax
DAT_Easter( dDate )  dEaster
Parameters
dDate date to process.
Returns
dEaster Easter date.
Example
? DAT_Easter( {31/12/1998} ) && 12/04/1998

Date Functions
DAT_IsLeap() : Is this a leap year?
Syntax
DAT_IsLeap( dDate )  lLeap
Parameters
dDate date to determine if it belongs to a leap year.
Returns
lLeap .T. if dDate belongs to a leap year; .F. if not.
Example
? DAT_IsLeap( {18/09/2000} ) && .T.
? DAT_IsLeap( {18/09/1999} ) && .F.
DAT_jtod() : Julian date to date.

Alias
jtod() .
Syntax
DAT_jtod( nJulian )  dDate
Parameters
nJulian the Julian date to convert.
Returns
dDate date expression of nJulian .
Example
? DAT_jtod( 2450813 ) && { 30-12-97 }
? DAT_jtod( DAT_num( DATE() ) ) && returns DATE()
? DAT_jtod( DAT_num( DATETIME() ) ) && returns DATE()
DAT_LastVersion() : Returns the file stamp of DAT functions.

Remark
Syntax
DAT_LastVersion()  szLastVersion
Parameters
None.

Date Functions
Returns
"C:\Focus\5.0\DATES.C-Mon Oct 19 15:55:22 1998" .
DAT_month() : Returns the number of the month for a given

date.
Syntax
DAT_month( dDate )  nMonth
Parameters
dDate date to obtain the month of.
Returns
nMonth day (from 1 to 12).
Example
? DAT_month( {31/12/1998} ) && 12
DAT_num() : Converts a date into a number (Julian date).

Alias
DAT_dtoj() , dtoj() .
Syntax
DAT_num( dDate|tDateTime )  nNumber
Parameters
or...
tDateTime datetime expression to convert.
Returns
nNumber number that represents the dDate parameter. This is also known as the Julian date.
Example
? DAT_num( { 30-12-97 } ) && 2450813
? DAT_num( { 31-12-97 } ) && 2450814
? DAT_num( DATE() ) && Strictly equivalent to ? SYS(11,DATE())
? DAT_num( DATE() ),DAT_num( DATETIME() ) && 2451312,0000 2451312,423981482000000
See also
DAT_jtod() .

Date Functions
DAT_NumberOfDays() : Returns the number of days in a
month.
Alias
DAT_DaysInMonth() .
Syntax
DAT_NumberOfDays( nMonth )  nDays
Parameters
nMonth month number (1, 2, ...,12).
Returns
nDays number of days in the nMonth month. Warning : the month of February always returns 28
days!
Example
? DAT_NumOfDays( 1 ) && 31
? DAT_NumOfDays( 2 ) && 28 (ALWAYS)
DAT_stod() : Transforms a YYYYMMDD date string into a

FoxPro date (opposite to DTOS()).
Syntax
DAT_stod( szDate )  dDate
Parameters
szDate date string to convert.
Returns
dDate date corresponding to the szDate parameter.
Example
? DAT_stod( "19981231" ) && {31/12/1998}
DAT_year() : Returns the year from the specified date.

Syntax
DAT_year( dDate )  nYear
Parameters
dDate date to obtain the year of.
Returns
nYear year.

Date Functions
Example
? DAT_year( {31/12/1998} ) && 1998
DAT_ymd() : Splits a date into its basic components.

Alias
DAT_split() .
Syntax
DAT_ymd( dDate,@nYear,@nMonth,@nDay )  .T.
Parameters
dDate date to split.
nYear variable in which the Year component will be stored. The parameter MUST be passed by
reference.
nMonth variable in which the Month component will be stored. The parameter MUST be passed by
reference.
nDay variable in which the Day component will be stored. The parameter MUST be passed by
reference.
Returns
.T. the function always returns .T. .
Example
LOCAL nYear,nMonth,nDay
nYear = 0
nMonth = 0
nDay = 0
DAT_ymd( {31/12/1998},@nYear,@nMonth,@nDay )
? nYear && 1998

? nMonth && 12
? nDay && 31

DBF Functions
DBF Functions

DBF Functions
DBF_append() : Appends a new record or a series of records.

Syntax
DBF_append( [nHowMany],[nWorkArea] )  .T.
Parameters
nHowMany number of records that must be added. Default is 1 record.
nWorkArea optional work area number. When not passed, the function operates on the current work area
(nWorkArea = -1 ).
Returns
DBF_bot() : Is the table at begin of file?

Alias
DBF_BeginOfTable()
Syntax
DBF_bot( [nWorkArea] )  lTableStatus
Parameters
nWorkArea optional work area number. When not passed, the function returns the table status for the
current work area (nWorkArea = -1).
Returns
lTableStatus .T. if table is at first record; .F. otherwise.
DBF_commit() : Flushes current record to disk.

Syntax
DBF_commit( [nWorkArea] )  lSuccess
Parameters
(nWorkArea = -1 ).
Returns
lSuccess .T. if COMMIT was successful; .F. otherwise.
DBF_empty() : Is it an empty table?

Syntax
DBF_empty( [nWorkArea] )  lStatus

DBF Functions
Parameters
(nWorkArea = -1 ).
Returns
lStatus .T. if empty table (no record); .F. otherwise.
DBF_eot() : Is the table at end of file?

Alias
DBF_EndOfTable()
Syntax
DBF_eot( [nWorkArea] )  lTableStatus
Parameters
nWorkArea optional work area number. When not passed, the function returns the table status for the
current work area (nWorkArea = -1).
Returns
lTableStatus .T. if table is at last record; .F. otherwise.
DBF_exclu() : Table open exclusively?

Alias
DBF_IsExclusive()
Syntax
DBF_exclu( [nWorkArea] )  lExclusive
Parameters
(nWorkArea = -1 ).
Returns
lExclusive .T. if table opened exclusively; .F. otherwise.
DBF_GoBottom() : Go to the bottom of a given work area.

Syntax
DBF_GoBottom( [nWorkArea] )  nRecord
Parameters
(nWorkArea = -1 ).

DBF Functions
Returns
nRecord current record number.
See also
DBF_GoTop() , DBF_Skip() .
DBF_GoTop() : Go to the top of a given work area.

Syntax
DBF_GoTop( [nWorkArea] )  nRecord
Parameters
(nWorkArea = -1 ).
Returns
nRecord current record number.
See also
DBF_GoBottom() , DBF_Skip() .
DBF_flockd() : Table locked or open exclusively?

Alias
DBF_IsTableLocked()
Syntax
DBF_flockd( [nWorkArea] )  lFLocked
Parameters
(nWorkArea = -1 ).
Returns
lFLocked .T. if table locked or opened exclusively; .F. otherwise.
DBF_LastVersion() : Returns the file stamp of DBF functions.

Remark
Syntax
DBF_LastVersion()  szLastVersion

DBF Functions
Parameters
None.
Returns
"C:\Focus\5.0\DBF.C-Mon Oct 19 15:55:22 1998" .
DBF_lock() : Locks a file or a record.

Syntax
DBF_lock( [nLockMethod],[nWorkArea] )  lSuccess
Parameters
nLockMethod locking method (0 = RECORD , 1 = FILE ). Default is RECORD .
(nWorkArea = -1 ).
Returns
lSuccess .T. if lock is successful; .F. otherwise.
DBF_readon() : Table open without write access?

Alias
DBF_IsReadOnly()
Syntax
DBF_readon( [nWorkArea] )  lReadOnly
Parameters
(nWorkArea = -1 ).
Returns
lReadOnly .T. when table opened in READ ONLY mode (no write access); .F. otherwise.
DBF_reccnt() : Number of records.

Alias
DBF_Reccount(), DBF_LastRec()
Syntax
DBF_reccnt( [nWorkArea] )  nRecords
Parameters
(nWorkArea = -1 ).

DBF Functions
Returns
nRecords 0 if table is empty; otherwise number of records.
DBF_replac() : Replaces a field with a value.

Alias
DBF_Replace()
Syntax
DBF_replac( szField,xValue )  lSuccessful
Parameters
szField field to be replaced with xValue .
xValue value to replace cField with.
Returns
lSuccessful .T. if REPLACE was successful; .F. otherwise.
DBF_rlockd() : Current record locked, table locked or table

open exclusively?
Alias
DBF_IsRecordLocked()
Syntax
DBF_rlockd( [nWorkArea] )  lRLocked
Parameters
(nWorkArea = -1 ).
Returns
lRLocked .T. if current record is locked, or if table is locked or if table is opened exclusively; .F.
otherwise.
DBF_seek() : Performs a SEEK.

Alias
DBF_LookUp(), DBF_search()
Comment
This function operates on current work area only.
Syntax
DBF_seek( xValue )  lFound

DBF Functions
Parameters
xValue value to look for.
Returns
lFound .T. if value FOUND() ; .F. otherwise.
DBF_Skip() : Skips a specified number of records in a given

work area.
Syntax
DBF_Skip( [nWorkArea[,nRecords]] )  nRecord
Parameters
(nWorkArea = -1 ).
nRecords optional number to skip. When not passed, the function skips 1 record forward in the table
(+1). Negative numbers can be used to skip backward.
Returns
nRecord current record number or a negative number if the function failed.
See also
DBF_GoTop() , DBF_GoBottom() .
DBF_status() : Retrieves the status of a DBF.

Syntax
DBF_status( [nWorkArea] )  nStatus
Parameters
(nWorkArea = -1 ).
Returns
nStatus DBF status.
Manifest Constant Value Description

#define DB_BOF 1 BOF()
#define DB_EOF 2 EOF()
#define DB_RLOCKED 4 Current record is RLOCKed
#define DB_FLOCKED 8 Database is FLOCKed
#define DB_EXCLUSIVE 16 Database is open EXCLUSIVEly
#define DB_READONLY 32 Database is READONLY

DDA Functions
Data Driven Application Functions

DDA Functions
Functions Synopsis
DDA_*() functions of FOCUS.FLL make it possible to write a small Visual FoxPro interpreter. It's very usual in the
Xbase world to see applications executing variable code, code maintained in data files, and the likes … even code that
modifies itself, a very powerful feature but also somewhat dangerous to put in use. No doubt that Artificial Intelligence
uses this kind of technique to create morphing objects.
With version 5.13 a set of new functions has been added to FOCUS.FLL that are really powerful but also a bit
dangerous: DDA_Aliases() , DDA_Argc() , DDA_Argv() , DDA_IsFunction() , DDA_FuncPtr() ,
DDA_SetExecPtr() , DDA_ExecFuncPtr() . In fact they are only dangerous through the use of the
DDA_ExecFuncPtr() function that really triggers the execution of the code pointed to by an internal code pointer.
These new functions are the core component of Artificial Intelligence routines that come within FOCUS but that are so
far kept completely invisible to you.
In the future, you might expect an application to dialog with another through FOCUS.FLL , exchanging information,
executing code in one another, etc.

DDA Functions
DDA_Aliases() : Returns all the aliases that are known for a

specified FOCUS.FLL function.
Syntax
MIS_Aliases()
Syntax
DDA_Aliases( szFunction )  szAliases
Parameters
szFunction function to look for in FOCUS.FLL . The function is case insensitive. Don’t include parenthesis in
the function name.
Returns
szAliases a string with all known aliases of a given function. Each alias is semi-colon separated from the
other. The return value is an empty string is the function is not found. The function name is also
listed in the aliases of the function.
Example
? DDA_Aliases( "MIS_Vers" ) && "MIS_VER;MIS_VERS;MIS_VERSION"
DDA_Argc() : Number of arguments that a specified function of

FOCUS.FLL expects.
Alias
MIS_Argc(), MIS_Pcount(), DDA_Pcount()
Syntax
DDA_Argc( szFunction )  nParams
Parameters
the function name.
Returns
nParams number of parameters or –1 if the function is not found.
Example
? DDA_Argc( "MIS_IsFunction" ) && 1
See also
DDA_Argv() , DDA_Syntax()
DDA_Argv() : Argument types that a specified function of

FOCUS.FLL expects.
Alias
MIS_Argv(), MIS_Plist(), DDA_Parameters(), DDA_Params(), DDA_ParamTypes(), DDA_Plist()

DDA Functions
Syntax
DDA_Argv( szFunction )  szParamTypes
Parameters
the function name.
Returns
szParamTypes parameter types or an empty string is the function is not found. If the specified function does
not expect any parameter, DDA_Argv() also returns an empty string.
"" No parameter
"0" .NULL.
"?" Any type can be passed
"C" Character type
"D" Date type
"I" Integer type
"L" Logical type
"N" Numeric type
"R" Reference
"T" Datetime type
"Y" Currency type
Example
? DDA_Argv( "MIS_False" ) && ".?,.?,.?,.?,.?,.?,.?,.?,.?,.?"
DDA_count() : Returns the number of Visual FoxPro

commands, and evaluations performed by the FOCUS.FLL
interpreter engine.
Syntax
DDA_count( [nReset] )  nCalls
Parameters
nReset resets the internal counter to nReset calls.
Returns
nCalls number of calls submitted to internal evaluation.
Example
LOCAL lResult
LOCAL xResult
&& Consider the Var variable to be not existing

lResult = DDA_Evaluate( "Var" ) && .T.
IF ( lResult )
IF ( DDA_ExtendedError() != 0 )
? "The following error has occurred : " + DDA_ExtendedErrorMessage()
ENDIF
ENDIF
&& Consider the Blabla() function to be not existing

lResult = DDA_Evaluate( "Blabla" ) && .T.
IF ( lResult )

DDA Functions
ENDIF
ENDIF
Var = 741
xResult = DDA_Evaluate( "Var" )
? "Var is unknown"
ELSE
? "Var is equal to ",xResult
ENDIF
? DDA_Evaluate("DATE(.T.)") && .T.

? DDA_ExtendedErrorMessage() && "Too many arguments."
? DDA_Evaluate("TIME()") && 23:01:39
? DDA_count() && 5 (because 5 calls to DDA_Evaluate() performed)
See also
DDA_ResetCounter()
DDA_CloseLog() : Closes the DDA log file.

Remark
From the moment a log file has been indicated to the FOCUS.FLL engine, to the moment that FOCUS.FLL is released
from memory, any DDA log file set with DDA_SetLog() is opened in an exclusive mode. Therefore, it cannot be
viewed, printed, or accessed in any manner. However, FOCUS.FLL provides an easy method to close it thanks to the
DDA_CloseLog() function. Once the DDA_CloseLog() function has been called, the FOCUS.FLL interpreter engine
won’t log errors in the DDA log file anymore. If this is needed, the log file has to be re-established.
Syntax
DDA_CloseLog()  .T.
Parameters
None.
Returns
Example
LOCAL szLogFile
szLogFile = "C:\MYDDA.LOG"
IF ( DDA_SetLog( szLogFile ) )
DDA_execute( "WAIT WINDOW ‘There is no error here’ NOWAIT" ) )
IF ( ! DDA_execute( "WAIT WINDOWBADABOUM ‘Error!’ NOWAIT" ) ) )
szLogFile = DDA_GetLog() && Get the name of the log file
DDA_CloseLog() && Close the log file now
MODIFY COMMAND ( szLogFile ) && Edit the log file
DDA_SetLog( szLogFile ) && Re-establish the log file
ENDIF
ENDIF

DDA Functions
DDA_error() : Last operation internal error code.
Remark
We recommend to use the DDA_ExtendedError() and DDA_ExtendedErrorMessage() functions instead.
Syntax
DDA_error()  nError
Parameters
None.
Returns
nError last operation internal error code.
DDA_Evaluate() : Evaluates an expression.

Remark
The DDA_Evaluate() function makes it easy to execute and test function calls or variables. It is especially designed
for Data Driven Applications where parameters of an application can actually be code. Although very powerful, under
various circumstances, the Expression Evaluator of Visual FoxPro can raise errors. This is the case when the error #67
is generated: An internal consistency check in the Visual FoxPro expression evaluator failed. A Visual FoxPro damaged
object file might cause this. Recompile the program that caused the error. Therefore, you might be well inspired to set
up a local Error Handler before calling DDA_evaluate() and reset the Error Handler to what it was after
DDA_Evaluate() . This can be easily done with the following code:
LOCAL xValue && Return of the expression to evaluate

LOCAL lError && Local variable to trap VFP error
LOCAL OldHandler && Old Error Handler
OldHandler = ON( "ERROR" ) && Save Old error handler

ON ERROR lError = .T. && Set this var to .T. if VFP error
xValue = DDA_Evaluate( szToExecute ) && Evaluate the expression now
ON ERROR &OldHandler && Re-assign old error handler
IF ( lError ) && If VFP raised an error

? "The expression cannot be evaluated
ELSE
&& VFP didn't raised any error but that does not mean that everything is OK
&& Now ... let's see if we got an error evaluating the expression
&& (the expression could be evaluated)
? "The expression is invalid"
ELSE
? "The expression is evaluated to",xValue
ENDIF
ENDIF
Syntax
DDA_Evaluate( szExpr )  xValue
Parameters
szExpr expression to evaluate. You can evaluate command lines such as MyVar = 16 and hoping that
it will assign 16 to MyVar . It will evaluate the expression instead, trying to figure out if MyVar
is equal to 16. If you want to execute command lines, you should call the DDA_execute()
function.

DDA Functions
Returns
xValue the value corresponding to the szExpr expression. If the expression is invalid, a .T. value is
returned. This does not indicate that the szExpr returned a .T. value nor does it mean that
the DDA_Evaluate() call was successful. It is the default data type and value that Visual
FoxPro uses. If the return value of DDA_Evaluate() is .T., you should test whether you have
raised an error or not. Do this with the DDA_ExtendedError() function. If it returns 0, it
means that szExpr is really evaluated to .T. ; if it returns another error code, then you should
check with the FoxPro technical reference to have an explicit error message, or call the
DDA_ExtendedErrorMessage() function of FOCUS.FLL that will do this for you.
Example
LOCAL lResult
LOCAL xResult

IF ( lResult )
ENDIF
ENDIF

IF ( lResult )
ENDIF
ENDIF
Var = 741
? "Var is unknown"
ELSE
ENDIF

? DDA_count() && 5 (because of 5 calls to DDA_Evaluate())
DDA_ExecFuncPtr() : Executes the code that is pointed to by

the internal execution pointer.
Alias
MIS_ExecFuncPtr()
Caution
The DDA_FuncPtr() , DDA_SetExecPtr() and DDA_ExecFuncPtr() are very powerful functions with which you
can build amazing features such as code that modifies itself. However they are also very dangerous. It goes far
beyond macros and is also much quicker because it never implies a compilation process of any sort.
If the parameters that are passed to this function do not correspond to the ones that are expected by the
function pointed to by the internal code pointer, unpredictable results will happen, often terminating the
current application by causing an illegal operation.
Syntax
DDA_ExecFuncPtr( <parameters> )  xValue

DDA Functions
Parameters
<parameters> list of parameters coping with the parameters of the function that should be executed.
Returns
xValue the return of the function obtained by DDA_SetExecPtr() .
Example
LOCAL FuncPtr
FuncPtr = DDA_FuncPtr("STR_mirror")
IF ( FuncPtr != -1 )
&& Set up the internal code pointer
DDA_SetExecPtr( FuncPtr )
&& Execute the function of FOCUS.FLL that's located at that place
&& This will correspond to STR_mirror( "Hello" ) !!!
? DDA_ExecFuncPtr( "Hello" ) && "olleH"
ENDIF
See also
DDA_SetExecPtr() , DDA_FuncPtr() .
DDA_Execute() : Executes a command line.

Alias
DDA_execut(), Execute()
Syntax
DDA_Execute( szCommand )  lSuccess
Parameters
szCommand Visual FoxPro instruction to execute.
Returns
lSuccess .T. if the command was successfully carried; .F. otherwise. If the command cannot be
executed, the FOCUS.FLL library does not raise any error! This feature can be extremely
powerful in applications that are essentially based on external code (code found in external
files, or placed in databases, etc.).
Example
? DDA_Execute( "WAIT WINDOW ‘Hello World’" ) && .T.
? DDA_Execute( "This command does not exist" ) && .F.
DDA_ExecuteFile() : Executes a set of commands contained in

a file.
Alias
DDA_filexe(), DDA_FileExecute()
Syntax
DDA_ExecuteFile( szFile )  lSuccess

DDA Functions
Parameters
szFile commands to execute. Please notice that the file cannot contain controls structures such as
IF ... ENDIF , DO WHILE ... ENDDO , FOR ... NEXT , DO CASE ... ENDCASE , etc.
Function and procedure definition is not supported either.
Returns
lSuccess .T. if the command file was successfully executed; .F. otherwise. It can be that the file
contained many execution faults, which does not influence the return of the function!
Example
IF ( ! DDA_ExecuteFile( "MYFILE.PGM" ) )
? "Cannot execute command file"
ENDIF
DDA_ExecuteSnapIn() : Executes a snap-in file.

Alias
ExecuteSnapIn()
Caution
The DDA_ExecuteSnapIn() , function is very similar to the DDA_ExecuteFile() however, the execution file must
be tagged with a well-defined mark at the first line: "FW1.0" . This precaution was needed to be able to distinguish
between different interpreter engines.
Syntax
DDA_ExecuteSnapIn( szFile )  lSuccess
Parameters
szFile file to execute.
Returns
lSuccess .T. if the file was correctly executed; .F. if not.
See also
DDA_ExecuteFile()
DDA_ExtendedError() : Last operation Visual FoxPro error

code.
Caution
VFP 5 seems to handle error codes correctly as far as the 1229 and 1230 error codes are concerned. VFP 6 screws up!
Try the following code in both instances:
ON ERROR WAIT WINDOW ALLTRIM(STR(ERROR()))+":"+MESSAGE()
? DATE(1) && VFP5 : "1230:Too many arguments."
&& VFP6 : "1229:Too few arguments."
Syntax
DDA_ExtendedError()  nError

DDA Functions
Parameters
None.
Returns
nError the Visual FoxPro error code or 0 if no error occurred.
Example
LOCAL lResult
LOCAL xResult

IF ( lResult )
ENDIF
ENDIF

IF ( lResult )
ENDIF
ENDIF
Var = 741
? "Var is unknown"
ELSE
ENDIF

? DDA_count() && 5 (because 5 calls to DDA_Evaluate() were performed here)
DDA_ExtendedErrorMessage() : Last operation Visual FoxPro

error message.
Caution
VFP 5 seems to handle error codes correctly as far as the 1229 and 1230 error codes are concerned. VFP 6 screws up!
Try the following code in both instances:
ON ERROR WAIT WINDOW ALLTRIM(STR(ERROR()))+":"+MESSAGE()
? DATE(1) && VFP5 : "1230:Too many arguments."
&& VFP6 : "1229:Too few arguments."
Syntax
DDA_ExtendedErrorMessage()  szError
Parameters
None.
Returns
szError the Visual FoxPro error message or "" if no error occurred.

DDA Functions
Example
LOCAL lResult
LOCAL xResult

IF ( lResult )
ENDIF
ENDIF

IF ( lResult )
ENDIF
ENDIF
Var = 741
? "Var is unknown"
ELSE
ENDIF

? DDA_count() && 5 (because 5 calls to DDA_Evaluate() were performed here)
DDA_GetLog() : Gets the log file in which commands that

couldn’t be executed are logged.
Caution
The DDA log file is constantly opened EXCLUSIVELY from the moment you have specified a log file to the moment you
close down FOCUS.FLL . This is quite normal, otherwise, FOCUS.FLL would have to open the log file too frequently
during execution. Therefore, the DDA log file cannot be viewed unless you use the DDA_CloseLog() function.
Alias
DDA_GetLogFile(), GetDDALogFile(), GetDDALog()
Syntax
DDA_GetLog()  szLogFile
Parameters
None.
Returns
szLogFile the DDA log file or an empty string if there is none.
Example
DDA_SetLog( "C:\MYDDA.LOG" )
? DDA_GetLog() && "C:\MYDDA.LOG"

DDA Functions
DDA_GetStop() : Retrieves the current Error Handler routine.
Syntax
DDA_GetStop()  szCurStopProc
Parameters
None.
Returns
szCurStopProc current Error Handler routine for DDA routines used if Error Handling strategy is set to 1.
DDA_FuncPtr() : Returns a function pointer to a specified

function contained in FOCUS.FLL
Alias
MIS_FuncPtr()
Syntax
DDA_FuncPtr( szFunction )  nPointer
Parameters
szFunction function to look for in FOCUS.FLL or –1 if the function was not found.
Returns
nPointer code pointer within FOCUS.FLL .
Example
SET LIBRARY TO FOCUS.FLL
DISPLAY STATUS
&& You should have a list such as the one that follows:
BMP_BITS 10001490
BMP_COLORS 100014B0
BMP_HEADER 100014D0
BMP_HEIGHT 10001450
BMP_ISBMP 10001210
BMP_WIDTH 10001470
CD_BAYOPE 1000B860
CD_BAYCLO 1000B890
CD_CANEJE 1000BA40
CD_CANPLA 1000BAA0
<etc.>
? NUM_hexa( DDA_FuncPtr( "CD_CANPLA" ) ) && 1000BAA0
DDA_IsFunction() : Returns .T. if a specified function exists in

FOCUS.FLL.
Alias
MIS_IsFunction()
Syntax
DDA_IsFunction( szFunction )  lExist

DDA Functions
Parameters
the function name.
Returns
lExist .T. if function szFunction exists; .F. otherwise.
Example
? DDA_IsFunction( "MIS_Vers" ) && .T.
DDA_LastVersion() : Returns the file stamp of DDA functions.

Remark
Syntax
DDA_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\DDA.C-Mon Oct 19 15:55:22 1998" .
DDA_ResetCounter() : Resets the internal DDA counter to 0.

Alias
DDA_Reset(), ResetDDACounter(), ResetDDACount()
Syntax
DDA_ResetCounter()  .T.
Parameters
None.
Returns
See also
DDA_Count()

DDA Functions
DDA_SetExecPtr() : Assigns the internal execution pointer to a
given value.
Alias
MIS_SetExecPtr()
Syntax
DDA_SetExecPtr( nPointer )  .T.
Parameters
nPointer code pointer within FOCUS.FLL . Typically, the nPointer pointer is obtained via the
DDA_FuncPtr() function.
Returns
Example
LOCAL FuncPtr
FuncPtr = DDA_FuncPtr("STR_mirror")
DDA_SetExecPtr( FuncPtr )
? DDA_ExecFuncPtr( "Hello" ) && "olleH"
ENDIF
DDA_SetLog() : Sets the log file in which commands that

couldn’t be executed are logged by the FOCUS engine.
Caution
The DDA log file is constantly opened EXCLUSIVELY from the moment you have specified a log file to the moment you
close down FOCUS.FLL . This is quite normal, otherwise, FOCUS.FLL would have to open the log file too frequently
during execution. Therefore, the DDA log file cannot be viewed.
Alias
DDA_SetLogFile(), SetDDALogFile(), SetDDALog()
Syntax
DDA_SetLog( szLogFile )  lSuccess
Parameters
szLogFile the DDA log file to set. FOCUS.FLL accepts only once the setting of the log file: once it has
been set, it cannot be overwritten before another session of FOCUS.FLL .
Returns
lSuccess .T. if the DDA log file was successfully set; .F. otherwise.
Example
IF ( DDA_SetLog( "C:\MYDDA.LOG" ) )
? DDA_GetLog() && "C:\MYDDA.LOG"

DDA Functions
DDA_SetLog( "C:\YOURDDA.LOG" ) && Will fail because the log file was already set
ENDIF
DDA_SetStop() : Customizes the Error Handler routine that

must be used when execution errors occur.
Syntax
DDA_SetStop( szProc )  szCurProc
Parameters
szProc procedure that must be executed when an error occurs in the FOCUS.FLL interpreter engine.
This procedure will only be executed if the Error Handling strategy is set to 1 (see
DDA_stop() ).
Returns
szCurProc current procedure.
Example
DDA_SetStop( "DO MyErrorHandler WITH DDA_ExtendedError()" ) )
DDA_stop( 1 ) && Use custom error handler
DDA_execute( "Mistake" ) && Should trigger MyErrorHandler!
PROCEDURE MyErrorHandler( nError )

WAIT WINDOW "Error #" + ALLTRIM(STR(nError)) + " : " + ;
DDA_ExtendedErrorMessage() NOWAIT
RETURN
DDA_Stop() : Sets the strategy that FOCUS.FLL has to follow

whenever there is a execution error.
Syntax
DDA_Stop( [nStrategy] )  nCurrentStrategy
Parameters
nStrategy strategy to follow:
Value Meaning
0 FOCUS.FLL continues execution
1 FOCUS.FLL should execute a given procedure
2 FOCUS.FLL should generate a VFP error
3 FOCUS.FLL should generate a custom error (not
supported yet)
This parameter is optional. When not passed, the function simply returns the current strategy
status. The default strategy used by FOCUS.FLL is 0: no stop!
Returns
nCurrentStrategy the current strategy used by FOCUS.FLL .

Common Dialog Functions

Functions Synopsis
FOCUS.FLL comes with several enhancements over the standard common dialogs. Common Dialog Boxes make it
simple for an application to call single functions rather than creating complex dialog box procedures with resource file,
etc.
FoxPro already provides such services through the well known GETFILE() , GETDIR() , GETFONT() functions.
However, we wanted to give the developer tighter control.
Each standard dialog is taken from the COMMDLG.DLL that provides a default procedure and template for each type
of common dialog box.

DLG_color() : Selects a color.

Comment
DLG_color() is somewhat similar to Visual FoxPro GETCOLOR() function. However it offers different control over the
standard dialog box.
Syntax
DLG_color( nRGBInitColor,nFlags[,nHwnd] )  nRGBColor
Parameters
nRGBInitColor specifies the color initially selected when the dialog box is created.
When the dialog box is created, the system selects the nearest solid color available if the
CC_RGBINIT flag is specified in the Flags member and the value of this member is not among
the available colors. If this member is not valid, the color initially selected is black.
nFlags dialog box flags:
#define CC_RGBINIT 0x00000001

#define CC_FULLOPEN 0x00000002
#define CC_PREVENTFULLOPEN 0x00000004
#define CC_SHOWHELP 0x00000008
Flags can be mixed to allow multiple settings.
nHwnd optional owner window handle. By default, the DLG_color() function uses the main FoxPro
window handle.
Returns
nRGBColor RGB color, or -1 if Cancel was selected.
Example
* Init with color corresponding with RGB( 192,192,192 ) = 1
* Make it impossible to define new predefined colors = 4
* ---------------------------------------------------------
= 5
? DLG_color( RGB( 192,192,192),5 )

* Init with color corresponding with RGB( 128,128,128 ) = 1

* Open it in the full mode = 2
* ---------------------------------------------------------
= 3
? DLG_color( RGB( 128,128,128 ),3 )
DLG_font() : Selects a font.

Comment
DLG_font() is somewhat similar to FoxPro GETFONT() function. However it offers different control over the
standard dialog box.
Syntax
DLG_font( nRGBInitColor,nMinSize,nMaxSize,nFlags )  szFont

Parameters
nRGBInitColor specifies the color initially used for the Sample box when the dialog box is created.
nMinSize specifies the minimum point size a user can select. You must set the CF_LIMITSIZE flag
member.
nMaxSize specifies the maximum point size a user can select. You must set the CF_LIMITSIZE flag
member.
#define CF_SCREENFONTS 0x00000001L

#define CF_PRINTERFONTS 0x00000002L
#define CF_SHOWHELP 0x00000004L
#define CF_INITTOLOGFONTSTRUCT 0x00000040L
#define CF_USESTYLE 0x00000080L
#define CF_EFFECTS 0x00000100L
#define CF_APPLY 0x00000200L
#define CF_ANSIONLY 0x00000400L
#define CF_NOVECTORFONTS 0x00000800L
#define CF_NOSIMULATIONS 0x00001000L
#define CF_LIMITSIZE 0x00002000L
#define CF_FIXEDPITCHONLY 0x00004000L
// must also have CF_SCREENFONT
#define CF_WYSIWYG 0x00008000L
#define CF_FORCEFONTEXIST 0x00010000L
#define CF_SCALABLEONLY 0x00020000L
#define CF_TTONLY 0x00040000L
#define CF_NOFACESEL 0x00080000L
#define CF_NOSTYLESEL 0x00100000L
#define CF_NOSIZESEL 0x00200000L
Returns
szFont font name, font size, font style.
Example
* 385 corresponds to CF_SCREENFONTS + CF_EFFECTS + CF_USESTYLE
? DLG_font( 0,0,0,385 ) && "Arial,10,Regular" for example!
This example produces the following result:

DLG_LastVersion() : Returns the file stamp of DLG functions.

Remark
Syntax
DLG_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\DLG.C-Mon Oct 19 15:55:22 1998" .
DLG_open() : Open File Dialog Box.

See Also
See the FIL_get() function which is identical to get an extensive explanation about DLG_open() .
DLG_save() : Presents the Save File Dialog Box.

Syntax
DLG_save( szFileSpec,szWinTitle,szInitialDir,nFlags )  szFile

Parameters
szFileSpec pairs of null-terminated filter strings. The first string in each pair describes a filter (for example,
"Text Files" ), and the second specifies the filter pattern (for example, "*.TXT" ). Multiple
filters can be specified for a single item by separating the filter pattern strings with a semicolon
(for example, "*.TXT;*.DOC;*.BAK" ). The last string in the buffer must be terminated by
two NULL characters (CHR(0) ).
Filter expressions and filter patterns should be separated with NULL characters ( CHR(0) ).
szWinTitle window title.
szInitialDir initial directory.
#define OFN_READONLY 0x00000001

#define OFN_OVERWRITEPROMPT 0x00000002
#define OFN_HIDEREADONLY 0x00000004
#define OFN_NOCHANGEDIR 0x00000008
#define OFN_SHOWHELP 0x00000010
#define OFN_ENABLEHOOK 0x00000020
#define OFN_ENABLETEMPLATE 0x00000040
#define OFN_ENABLETEMPLATEHANDLE 0x00000080
#define OFN_NOVALIDATE 0x00000100
#define OFN_ALLOWMULTISELECT 0x00000200
#define OFN_EXTENSIONDIFFERENT 0x00000400
#define OFN_PATHMUSTEXIST 0x00000800
#define OFN_FILEMUSTEXIST 0x00001000
#define OFN_CREATEPROMPT 0x00002000
#define OFN_SHAREAWARE 0x00004000
#define OFN_NOREADONLYRETURN 0x00008000
#define OFN_NOTESTFILECREATE 0x00010000
#define OFN_NONETWORKBUTTON 0x00020000
#define OFN_NOLONGNAMES 0x00040000
Following is an extract of the WIN32 API:
OFN_ALLOWMULTISELECT Specifies that the File Name list box allows multiple
selections. (If the dialog box is created by using a private
template, the definition of the File Name list box must contain
the LBS_EXTENDEDSEL value.)
OFN_CREATEPROMPT Specifies that the dialog box function should ask whether the
user wants to create a file that does not currently exist. (This
flag automatically uses the OFN_PATHMUSTEXIST and
OFN_FILEMUSTEXIST flags.)
OFN_ENABLETEMPLATE Causes the operating system to create the dialog box by
using the dialog box template identified by hInstance and
lpTemplateName.
OFN_ENABLETEMPLATEHANDLE Indicates that hInstance identifies a data block that contains a
preloaded dialog box template. The operating system ignores
lpTemplateName if this flag is specified.
OFN_EXTENSIONDIFFERENT Specifies that the user typed a filename extension that differs
from the extension.
OFN_FILEMUSTEXIST Specifies that the user can type only names of existing files in
the File Name entry field. If this flag is specified and the user
enters an invalid name, the dialog box procedure displays a
warning in a message box. If this flag is specified, the
OFN_PATHMUSTEXIST flag is also used.
OFN_HIDEREADONLY Hides the Read Only check box
OFN_NOCHANGEDIR Causes the dialog box to set the current directory back to
what it was when the dialog box was called.
OFN_NONETWORKBUTTON Hides and disables the Network button.
OFN_NOREADONLYRETURN Specifies that the returned file does not have the Read Only
check box checked and is not in a write-protected directory.

OFN_NOTESTFILECREATE Specifies that the file is not created before the dialog box is
closed. This flag should be specified if the application saves
the file on a create-nonmodify network sharepoint. When an
application specifies this flag, the library does not check for
write protection, a full disk, an open drive door, or network
protection. Applications using this flag must perform file
operations carefully, because a file cannot be reopened once
it is closed.
OFN_NOVALIDATE Specifies that the common dialog boxes allow invalid
characters in the returned filename. Typically, the calling
application uses a hook function that checks the filename by
using the FILEOKSTRING message. If the text box in the edit
control is empty or contains nothing but spaces, the lists of
files and directories are updated. If the text box in the edit
control contains anything else, nFileOffset and nFileExtension
are set to values generated by parsing the text. No default
extension is added to the text, nor is text copied to the buffer
specified by lpstrFileTitle.
If the value specified by nFileOffset is less than zero, the
filename is invalid. Otherwise, the filename is valid, and
nFileExtension and nFileOffset can be used as if the
OFN_NOVALIDATE flag had not been specified.
OFN_OVERWRITEPROMPT Causes the Save As dialog box to generate a message box if
the selected file already exists. The user must confirm
whether to overwrite the file
OFN_PATHMUSTEXIST Specifies that the user can type only valid paths and
filenames. If this flag is used and the user types an invalid
path and filename in the File Name entry field, the dialog box
function displays a warning in a message box.
OFN_READONLY Causes the Read Only check box to be checked initially when
the dialog box is created. This flag indicates the state of the
Read Only check box when the dialog box is closed.
OFN_SHAREAWARE Specifies that if a call to the OpenFile function fails because of
a network sharing violation, the error is ignored and the
dialog box returns the given filename. If this flag is not
specified, the registered message for SHAREVISTRING is sent
to the hook function with a pointer to a null-terminated string
for the path and filename in the lParam parameter.
Returns
szFile file(s) that has (have) been chosen.
Example
* Searching the C:\ directory (multiple file interface)
? DLG_save( "Wave files" + CHR(0) + "*.WAV" + CHR(0) + ;
"All files" + CHR(0) + "*.*" + CHR(0) + CHR(0), ;
"Save to...","C:\",0x00000200 )

* Searching the C:\ directory (normal interface)
? DLG_save( "Wave files" + CHR(0) + "*.WAV" + CHR(0) + ;
"Save to...","C:\",0 )

Editor Functions
Editor Functions

Editor Functions
Functions Synopsis
FOCUS.FLL uses built-in editor capabilities of Visual FoxPro. All these functions are available through the C API of
Visual FoxPro. It makes it possible to write a very small Word Processor not to be compared to MS-Word capabilities
but it can beat Editbox features any time. RTF controls are more powerful but also more difficult to manage. Editor
functions can only process text files!

Editor Functions
EDI_AutoIndent() : Auto indent flag.

Syntax
EDI_AutoIndent( nEditorHandle[,lStatus] )  lCurStatus
Parameters
nEditorHandle Editor Handle. This handle can be obtained by calling the EDI_Open() function.
lStatus .T. to ask Visual FoxPro to auto-indent lines in the editing window; .F. otherwise. If this
parameter is not passed, EDI_AutoIndent() simply returns the current status.
Returns
lCurStatus the current status. It is important to notice that if the lStatus parameter is passed, the
function returns the status before it sets it to something else.
EDI_Backup() : Backup flag.

Syntax
EDI_Backup( nEditorHandle[,lStatus] )  lCurStatus
Parameters
nEditorHandle editor Handle. This handle can be obtained by calling the EDI_Open() function.
lStatus .T. to ask Visual FoxPro to make backup files; .F. otherwise. If this parameter is not passed,
EDI_Backup() simply returns the current status.
Returns
EDI_Close() : Closes a file.

Syntax
EDI_Close( nEditorHandle )  nErrorCode
Parameters
Returns
nErrorCode 1 if the file editing window was closed without saving; 0 if the file was saved and the window
was closed.
EDI_Cut() : Copies the selected portion of the file to the

clipboard and deletes it from the editing window.
Syntax
EDI_Cut( nEditorHandle )  .T.

Editor Functions
Parameters
Returns
EDI_Delete() : Deletes the selected portion of the file.

Syntax
EDI_Delete( nEditorHandle )  lSuccess
Parameters
Returns
lSuccess .T. if the function was successful; .F. otherwise.
EDI_FileName() : Determines the name of the file that is

currently edited.
Syntax
EDI_FileName( nEditorHandle )  szFile
Parameters
Returns
szFile name of the file that is currently edited; an empty string is returned when no file is currently
edited that corresponds to nEditorHandle .
EDI_Dirty() : Determines whether the file has been changed.

Alias
EDI_HasChanged(), EDI_Changed(), EDI_IsChanged(), EDI_IsModified(), EDI_Modified()
Syntax
EDI_Dirty( nEditorHandle )  lChanged
Parameters
Returns
lChanged .T.. if the file was changed; .F. otherwise.

Editor Functions
EDI_GetLineNum() : Returns the line number a given offset
belongs to.
Syntax
EDI_GetLineNum( nEditorHandle[,nOffset] )  nLine
Parameters
nOffset offset position in the file. If this parameter is not passed, the EDI_GetLineNum() function
retrieves the line number of the current offset position.
Returns
nLine the function always returns .T. .
EDI_GetLinePos() : Returns the offset of the first character of

the specified line in the file in the specified editing
window.
Syntax
EDI_GetLinePos( nEditorHandle,nLine )  nOffset
Parameters
nLine line number.
Returns
nOffset offset of the first character of line nLine .
EDI_GetPos() : Returns the current offset position.

Alias
EDI_Tell()
Syntax
EDI_GetPos( nEditorHandle )  nOffset
Parameters
Returns
nOffset current offset position.

Editor Functions
EDI_GroupUndo() : Groups/ungroups undo selection.
Syntax
EDI_GroupUndo( nEditorHandle,lSyncPoint )  lSuccess
Parameters
lSyncPoint .T. to group separate actions as a single action for EDI_Undo() and EDI_Redo() ; .F. to
terminate grouping.
Returns
EDI_Insert() : Inserts a string in the editing window.

Syntax
EDI_Insert( nEditorHandle,szString )  lSuccess
Parameters
szString insertion text.
Returns
lSuccess .T. if the szString insertion text was inserted; .F. otherwise.
EDI_LastVersion() : Returns the file stamp of EDI functions.

Remark
Syntax
EDI_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\EDITOR.C-Mon Oct 19 15:55:22 1998" .

Editor Functions
EDI_Open() : Opens a file for editing.
Remarks
No more than 50 file can be opened simultaneously for editing. An Editor Handle value cannot be used with other
functions than the Editor functions of FOCUS.FLL .
Syntax
EDI_Open( szFile )  nEditorHandle
Parameters
szFile file to open.
Returns
nEditorHandle editor Handle. This handle will be used in all subsequent Editor functions. If no handle can be
associated, EDI_Open() returns –1.
EDI_Paste() : Copies the contents of the clipboard into the file

in the specified editing window.
Syntax
EDI_Paste( nEditorHandle )  .T.
Parameters
Returns
EDI_PosInView() : Determines whether a given position is

visible in the current view of the editing window.
Syntax
EDI_PosInView( nEditorHandle[,nOffset] )  lVisible
Parameters
nOffset offset position in the file. If this parameter is not passed, the EDI_PosInView() function uses
the current offset position.
Returns
lVisible .T. if the offset position is visible in the current view of the editing window; .F. otherwise.

Editor Functions
EDI_Redo() : Redoes the last action.
Syntax
EDI_Redo( nEditorHandle )  .T.
Parameters
Returns
EDI_Save() : Saves a file.

Syntax
EDI_Save( nEditorHandle )  .T.
Parameters
Returns
EDI_Select() : Selects the range between two offsets.

Syntax
EDI_Select( nEditorHandle,nBegOffset,nEndOffset )  lSuccess
Parameters
nBegOffset beginning offset position of selection.
nEndOffset ending offset position of selection.
Returns
EDI_SetPos() : Moves the insertion point to the specified

offset.
Syntax
EDI_SetPos( nEditorHandle,nOffset )  .T.
Parameters

Editor Functions
nOffset offset position.
Returns
EDI_StatusBar() : Reports line and column position on the

Visual FoxPro statusbar.
Syntax
EDI_StatusBar( nEditorHandle[,lStatus] )  lCurStatus
Parameters
lStatus .T. to ask for line and column display on the statusbar of Visual FoxPro; .F. otherwise. If this
parameter is not passed, EDI_StatusBar() simply returns the current status.
Returns
EDI_Undo() : Undoes the last action.

Syntax
EDI_Undo( nEditorHandle )  .T.
Parameters
Returns

Event Functions
Event Functions

Event Functions
Functions Synopsis
In FOCUS.FLL for FoxPro (as opposed to Visual FoxPro), there were numerous Event functions. These were no longer
needed with the advent of Visual FoxPro ... until we wanted to grab more control over event processing. For example,
with the advanced event scheme of FOCUS.FLL it is now possible to detect idle time and to branch the execution of
the program to a certain routine (see EVE_OnIdleInterval() , EVE_OnIdleCommand() ,
EVE_GetIdleSince() ).

Event Functions
EVE_CustomizeEventCommand() : Customizes the command

associated to a given event.
Syntax
EVE_CustomizeEventCommand( nEvent,szCmd )  lSuccess
Parameters
nEvent event number. The following events are supported by VFP and FOCUS.FLL :
#define activateEvent 1 Activate window

#define deactivateEvent 2 Deactivate window
#define showEvent 3 Show window
#define hideEvent 4 Hide window
#define updateEvent 5 Redraw window
#define sizeEvent 6 Size window event
#define moveEvent 7 Move window event
#define closeEvent 8 Close window
#define mouseDownEvent 9 Left mouse down
#define mouseUpEvent 10 Left mouse up
#define mMouseDownEvent 11 Middle mouse down event
#define mMouseUpEvent 12 Middle mouse up event
#define rMouseDownEvent 13 Right mouse down event
#define rMouseUpEvent 14 Right mouse up event
#define mouseMoveEvent 15 Mouse move event
#define mouseWheelEvent 16 Mouse wheel event
#define keyDownEvent 17 Key down
#define hotkeyEvent 18 An ON KEY LABEL was pressed
#define menuInitEvent 19 Menu initialization event
#define menuUpdateEvent 20 Menu update required
#define menuHitEvent 21 Menu hit
#define toolbarEvent 22 Toolbar button hit
#define alarmEvent 23 Alarm/Timer event
szCmd the command to associate to the specified event.
Returns
lSuccess .T. if the function is successful; .F. if not.
Remark
This function has been temporarily disabled for performance degradation. Please notice that the associated
command will only be fired at first null event.
EVE_End() : Ends event processing.

Alias
StopEvents(), TerminateEvents()
Syntax
EVE_End()  .T.
Parameters
None.
Event Functions
Returns
See Also
EVE_Start() .
EVE_GetIdleSince() : Gets the last time when an event did

occur that postponed the inactivity in a program.
Alias
GetIdleSince()
Syntax
EVE_OnIdleSince()  nMilliSeconds
Parameters
None.
Returns
nMilliSeconds tick count when the last event did happened.
See Also
EVE_OnIdleCommand() , EVE_OnIdleInterval()
Example
LOCAL szIdleInterval
LOCAL szIdleCommand
&& If we have to logout if there is too long idle time

IF ( oApp.ReadIni( "FDA","IdleCompliance" ) == "YES" )
&& Take the idle interval from the INI file
szIdleInterval = STR_dionly( oApp.ReadIni( "FDA","IdleInterval" ) )
&& If this idle time seems to be correct
IF ( ! EMPTY( szIdleInterval ) )
&& Idle command
szIdleCommand = ALLTRIM( oApp.ReadIni( "FDA","IdleCommand" ) )
&& If there is something to execute
IF ( ! EMPTY( szIdleCommand ) )
&& That's the command that must be executed when idle
EVE_OnIdleCommand( szIdleCommand )
&& Let's inform FOCUS about the idle interval
EVE_OnIdleInterval( VAL( szIdleInterval ) )
ENDIF
ENDIF
ENDIF
FUNCTION CheckIfTooLong()
LOCAL nMilliSeconds
nMilliSeconds = SYS_GetTickCount() - EVE_GetIdleSince()

WAIT WINDOW "You're inactive for " + ;
ALLTRIM( STR( nMilliSeconds / 1000 ) ) + "sec." NOWAIT
IF ( FILE( oApp.RunPath + "\waiting.wav" ) ) && If file exists

SND_play( oApp.RunPath + "\waiting.wav" ) && Play a sound
ENDIF
&& If we're not already busy with a logon

IF ( ! oApp.LogonBusy )
&& Activate the main window (see Step #58)

Event Functions
oApp.SetForegroundWindow( _SCREEN.caption )
&& And log off/log on service (for example)
LogoffLogon()
ENDIF
RETURN ( VOID )
EVE_LastError() : Last error encountered in EVE functions.

Syntax
EVE_LastError()  szLastError
Parameters
None.
Returns
szLastError last error that occurred while using the EVE_*() functions.
EVE_LastVersion() : Returns the file stamp of EVE functions.

Remark
Syntax
EVE_LastVersion()  szLastVersion
Parameters
None.
Returns
szLastVersion string identifying the last version of the functions set.
EVE_OnIdleCommand() : Gets/Sets the idle command.

Alias
OnIdleCommand()
Syntax
EVE_OnIdleCommand( [szCommand] )  szCurrentCommand
Parameters
szCommand command to be executed at the next idle time.
Returns
szCurrentCommand current command executed when idle interval is elapsed.

Event Functions
See Also
EVE_OnIdleInterval() .
Example
LOCAL szIdleCommand

&& Idle command
ENDIF
ENDIF
ENDIF
LOCAL nMilliSeconds


ENDIF

LogoffLogon()
ENDIF
RETURN ( VOID )
EVE_OnIdleInterval() : Gets/Sets the idle interval.

Alias
OnIdleInterval()
Syntax
EVE_OnIdleInterval( [nMilliSeconds] )  nInterval
Parameters
None.
Returns
nMilliSeconds number of milliseconds before executing the OnIdleCommand .
See Also
EVE_OnIdleCommand() .

Event Functions
Example
LOCAL szIdleCommand

&& Idle command
ENDIF
ENDIF
ENDIF
LOCAL nMilliSeconds


ENDIF

LogoffLogon()
ENDIF
RETURN ( VOID )
EVE_ResetIdleSince() : Resets the last event.

Remark
Under various circumstances you probably need to reset the internal last call milestone. For example, when a process
is entirely automatic, driven for example via a DDE conversation, we can consider that there is some kind of activity.
This activity, of course, is not monitored by FOCUS.FLL . By calling EVE_ResetIdleSince() during the DDE
conversation you will force FOCUS to reset its internal counter.
Alias
ResetIdleSince()
Syntax
EVE_ResetIdleSince()  .T.
Parameters
None.
Returns
.T. always.

Event Functions
See Also
EVE_GetIdleSince() .
Example
PROCEDURE DoTopic( nChannel,szAction,szItem,szData,szFormat,nAdvise )
LOCAL lResult
LOCAL szToPoke && Whatever needs to be fetched
&& Disable DDE because we don't want interruptions !

DDEEnabled( .F. )
oApp.Log.Append( "DDE communication" )
lResult = .F.
DO CASE
CASE ( szAction == "INITIATE" )
lResult = .T.
oApp.DDE.ConnectionCounter = oApp.DDE.ConnectionCounter + 1
EVE_ResetIdleSince()
CASE ( szAction == "EXECUTE" )
lResult = ProcessDDEExecute( nChannel , ;
szAction , ;
szItem , ;
szData , ;
szFormat , ;
nAdvise )
IF ( lResult )
ENDIF
CASE ( szAction == "REQUEST" )
lResult = ProcessDDERequest( nChannel , ;
szAction , ;
szItem , ;
szData , ;
szFormat , ;
nAdvise , ;
@szToPoke )
IF ( lResult )
DDEPoke( nChannel,szItem,szToPoke )
ENDIF
CASE ( szAction == "TERMINATE" )
lResult = .T.
oApp.DDE.ConnectionCounter = oApp.DDE.ConnectionCounter - 1
IF ( oApp.DDE.ConnectionCounter < 0 )
oApp.DDE.ConnectionCounter = 0
ENDIF
ENDCASE
&& Re-enable DDE services now

DDEEnabled( .T. )
RETURN ( lResult )
EVE_SetUserDefinedAtNullCommand() : Sets a command to

be launched at firts null event.
Remark
This function was somehow existing in FOCUS.FLL for FoxPro 2.6. Since then, it has been removed ... and now, here
we go again, reappears. Why? Because we actually found a need for it when developing advanced DDE techniques. For
example, when the DDEExecute() function is supposed to trigger, in the server, a modal process, the function will
return a logical .F. because the server didn't return on time (that is before the DDE timeout has elapsed). What's the
trick then? Well, simply let the server carry out the operation when it will have the time to do so and in the meantime
already return a logical .T. , informing the client that it has understood what is expected from it. Therefore ...
execution goes on, the server can already reply, and the operation will be executed at first NULL event.

Event Functions
Alias
SetUserDefinedAtNullCommand()
Syntax
EVE_SetUserDefinedAtNullCommand( [szCommand] )  szCurrentCommand
Parameters
szCommand the command that must be carried out when a null event is encountered (when the application
has nothing to do).
Returns
szCurrentCommand the current command. As soon as the command has been carried on, it is removed and won't
be executed again unless it is once again fetched in the queue of FOCUS.FLL .
Example
&& A typical example of what has been said is the case where the client
&& wants the server to display its About dialog box (assuming that this is
&& a modal process).
&& Imagine that the server receives a demand of execution of the "ABOUT"
&& item, and that it must execute the oApp.AboutBox() in respond for it.
&& The proper way for it would be to execute the following command then:
SetUserDefinedAtNullCommand( "oApp.AboutBox()" )
EVE_Start() : Starts event processing.

Syntax
EVE_Start()  .T.
Parameters
None.
Returns
See Also
EVE_End() .

FDB Functions
FOCUS Data File Functions

FDB Functions
Functions Synopsis
FOCUS.FLL provides now basic data file functions known as FDB_*() functions. You might ask why FOCUS.FLL has
such functions when it is mostly entirely written for Visual FoxPro, an unsurpassed database engine for the PC. Well,
that was needed to create Artificial Intelligence knowledge bases that FOCUS.FLL will address in future versions
without depending on external resources.
From within the C code the library will store information about what you do with it, how you use it, etc. For example,
imagine a function that tries to determine where a given application is located, MS-Word for example. When it is
found, FOCUS.FLL may decide to store this information for later retrieval and possibly pass this information to other
instances of FOCUS.FLL and FOCUS.VCX . If multiple paths are to be considered, FOCUS.FLL may decide to store
them all so that it can try locate the same application where it found it one day.
This information is actually stored in knowledge bases which are nothing else but FDB files.
This is the first version of FDB files. A first version usually means unstable and incomplete. FDB files face the same
problem as any computer product so don't expect too much from it in their current state. For example there is no
SEARCH nor INDEX capabilities; you cannot replace a single field with a value, etc.
FDB files data are encrypted by default.

FDB Functions
FDB_Append() : Appends a series of records to a FDB file.

Syntax
FDB_Append( nHandle,nCount )  nRecords
Parameters
nHandle handle to the FDB file.
nCount number of records to append to the FDB file.
Returns
nRecords number of records contained in the FDB file after the insertion.
FDB_Create() : Creates a FDB file.

Syntax
FDB_Create( szFile,szStructure )  lSuccess
Parameters
szFile name of the FDB file to create.
szStructure the file structure. Each field contains 4 tokens : a fieldname, a field type, a field length, and a
field description. Each token is separated by a semicolon. Each field is separated by a
semicolon.
Returns
lSuccess .T. if the FDB file is successfully created; .F. if not.
FDB_LastVersion() : Returns the file stamp of FDB functions.

Remark
Syntax
FDB_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\FDB.C-Mon Oct 19 15:55:22 1998" .

File Functions
File Functions

File Functions
Functions Synopsis
FOCUS.FLL gives a wide range of File functions for you to use.
It is claimed that the applications created with Visual FoxPro are compliant with Windows 95 and Windows NT. That
certainly means that, from this point, you'll have to deal with new file concerns.
The way Windows 95 and Windows NT handle files is very much different from what we used to know. Both operating
systems largely extended the file capabilities. They can even deal with different file systems simultaneously.
While it was quite usual to talk about the FAT, today we have to consider additional file systems such as NTFS, CDFS,
and HPFS in addition to the FAT system.
There is no doubt that the FAT system, even though less powerful, will still be the most frequently used system;
certainly for the users that need a flexible way to boot their system. Please note that the FAT system is the only
suitable one for floppies.
HPFS was originally created for the OS/2 platform. Windows NT recognizes the format for "backward compatibility"
with OS/2 (backward compatibility from the Microsoft stand point of view).
NTFS is the File System of Windows NT. NTFS uses the international Unicode convention to store the filenames.
CDFS is the File System used for CD-ROMs.
FAT is the old File System we all used. Windows 95 has extended this File System to support the long names
convention.
With NTFS, the File System distinguishes between upper and lower case filenames. This was mandatory in order to
preserve a certain compatibility with POSIX (Jeffrey Richter, Développer sous Windows 95 et Windows NT, Microsoft
Press).
The FOCUS library provides the SYS_volume() function to determine with which file system your program is actually
dealing:
&& The second parameter value indicates that the function

&& should return the File System Name
? SYS_volume( "C:\",5 ) && "FAT"
? SYS_volume( "E:\",5 ) && "CDFS"
You can also use the SYS_volume( <szRoot>,2 ) (obtain volume serial number) service of FOCUS to track down
disk changes. Since MS-DOS 4.0, the FORMAT command puts a serial number on each formatted disk.
SYS_volume( <szRoot>,3 ) (or SYS_MaxFileLength() ) can be used to exactly determine the maximum
filename length of a given system. You should use this function instead of hardcoding filename lengths in your
program:
LOCAL szFile
szFile = SPACE( SYS_MaxFileLength( SYS_curdri() + ":\" ) )
<rest of your code>
When developing business applications, always keep in mind that the user can now mix these four basic file systems
(FAT, NTFS, CDFS and HPFS). In addition, more file systems will probably exist in the future.
Another thing to pay attention to is Unicode, that's the reason why we provide the SYS_IsUnicodeOnDisk()
function! Only the NTFS and FAT file systems store filenames under the Unicode form. Should you need paths, and
filenames, the system will take in charge all the necessary conversions, but it's up to you to reserve enough space.

File Functions
We know that you don't have to heed this in your FoxPro application, because everything is transformed for you. But
don't forget, that in the event of a very simple C routine, you might get in troubles if you didn't reserve enough space
for your temporary buffers!
Starting with version 5.13 of FOCUS.FLL , a brand new set of File functions have appeared: FIL_open() ,
FIL_create() , FIL_tell() , FIL_seek() , etc. In fact these functions have always existed in FOCUS.FLL but
they were kept hidden. What these functions have to offer is really immense when you compare them to low-level
native FoxPro file functions. The most obvious advantage is their ability to open a file in a SHARED mode, both for
reading and for writing. But they go far beyond that when you use them in conjunction with the
FIL_SetOpenStrategy() function. Indeed, by the FIL_SetOpenStrategy() you control how the functions are
to operate, either working directly with the Win32 API or mimicking Visual FoxPro. Of course, as you may guess, you
better use the Win32 API that provides tighter control over a number of features.
I do not want to take you on a tour of all these features now but just consider what streams can do in the NTFS
format. Streams can be incredibly useful in many situations where you need to store many different data of variable
length within the same file. How do you specify a stream? By simply specifying a colon after the file name, and then
followed by the name of the stream. For example, when issued on a NTFS partition, the following code will create a
stream named MyStream in the file MYFILE.TXT:
#define WIN32API_STRATEGY 1
#define GENERIC_READ 0x80000000
#define GENERIC_WRITE 0x40000000
FIL_SetOpenStrategy( WIN32API_STRATEGY )
nHandle = FIL_create( "C:\MYFILE.TXT:MyStream",GENERIC_READ+GENERIC_WRITE )
FIL_write( nHandle,REPLICATE( "Hello",100 ) )
FIL_close( nHandle )
What this code does is simple: it creates a file called MYFILE.TXT and within that file it creates a stream: MyStream .
Now, when you attempt to open the file, thanks to an application such as NOTEPAD.EXE, what really seems to be
incredible is that the file seems to be empty. Even the length reported by the Explorer is 0! However, you have well
written a string of 500 bytes to it (100 * length of "Hello"). I would say that Streams seem to be files within files! Well,
Visual FoxPro does not permit to create streams where FOCUS.FLL does.

File Functions
FIL_AreFileAPIsANSI() : Determines whether a set of Win32 file

functions is using the ANSI or OEM character set code
page.
Syntax
FIL_AreFileAPIsANSI()  lANSI
Parameters
None.
Returns
lANSI .T. if the set of Win32 file functions is using the ANSI code page; .F. if the set of Win32 file
functions is using the OEM code page.
FIL_BrowseForComputer() : Displays a dialog box that enables

the user to select a computer.
Syntax
FIL_BrowseForComputers(), BrowseComputer(), BrowseComputers(), BrowseForComputer(),
BrowseForComputers()
Syntax
FIL_BrowseForComputer( szMessage )  szComputer
Parameters
szMessage message that is displayed above the tree view control in the dialog box. This message can be
used to specify instructions to the user.
Returns
szComputer computer that was chosen or an empty string if no computer was selected.
Example
LOCAL szComputer
szComputer = FIL_BrowseForComputer( "Choose a computer for the Post Office" )
IF ( ! EMPTY( szComputer ) )
? "Computer:",szComputer
ENDIF
FIL_BrowseForFolder() : Displays a dialog box that enables

the user to select a shell folder.
Syntax
FIL_BrowseForFolders(), BrowseFolder(), BrowseFolders(), BrowseForFolder(), BrowseForFolders()
Syntax
FIL_BrowseForFolder( szMessage )  szFolder

File Functions
Parameters
Returns
szFolder folder that was chosen or an empty string if no folder was selected.
Example
&& Old fashioned code :
LOCAL szDir
m.szDir = GETDIR()
IF ( ! EMPTY( m.szDir ) )
? "Directory:",m.szDir
ENDIF
&& New fashioned code :

LOCAL szDir
m.szDir = FIL_BrowseForFolder( "Choose a directory for the Post Office" )
IF ( ! EMPTY( m.szDir ) )
? "Directory:",m.szDir
ENDIF
FIL_BrowseForPrinter() : Displays a dialog box that enables

the user to select a printer.
Syntax
FIL_BrowseForPrinters(), BrowsePrinter(), BrowsePrinters(), BrowseForPrinter(), BrowseForPrinters()
Syntax
FIL_BrowseForPrinter( szMessage )  szPrinter
Parameters
Returns
szPrinter printer that was chosen or an empty string if no printer was selected.
Example
LOCAL szPrinter
szPrinter = FIL_BrowseForPrinter( "Choose a printer for the Post Office" )
IF ( ! EMPTY( szPrinter ) )
? "Printer:",szPrinter
ENDIF
FIL_Canonicalize() : Canonicalizes a path.

Syntax
FIL_Canonicalize( szPath )  szCanonPath

File Functions
Parameters
szPath path to be canonicalized.
Returns
szCanonPath canonicalized path.
Example
? FIL_canonicalize("..\SPOT2100\BITMAPS\..\BITMAPS" ) && "\SPOT2100\BITMAPS"
FIL_chdir() : Change Directory service.

Alias
ChDir(), CDir() . CD() , ChangeDirectory() , FIL_cd()
Syntax
FIL_chdir( szPath )  lSuccess
Parameters
szPath new default path to set.
Returns
lSuccess .T. if operation was successful, .F. otherwise.
Example
IF ( ! FIL_chdir( "C:\DVL\FOX" ) )
? "Attempt to change directory failed"
ENDIF
FIL_ClearArchived() : Clears the Archive attribute of a file.

Syntax
FIL_ClearArchived( szFile )  lSuccess
Parameters
szFile file whose attribute has to be changed.
Returns
lSuccess function successful or not?
FIL_ClearCompressed() : Clears the Compressed attribute of a

file.
Syntax
FIL_ClearCompressed( szFile )  lSuccess

File Functions
Parameters
Returns
FIL_ClearHidden() : Clears the Hidden attribute of a file.

Syntax
FIL_ClearHidden( szFile )  lSuccess
Parameters
Returns
FIL_ClearNormal() : Clears the Normal attribute of a file.

Syntax
FIL_ClearNormal( szFile )  lSuccess
Parameters
Returns
FIL_ClearReadOnly() : Clears the Read-Only attribute of a file.

Syntax
FIL_ClearReadOnly( szFile )  lSuccess
Parameters
Returns
FIL_ClearSystem() : Clears the System attribute of a file.

Syntax
FIL_ClearSystem( szFile )  lSuccess

File Functions
Parameters
Returns
FIL_ClearTmp() : Clears the Temporary attribute of a file.

Syntax
FIL_ClearTmp( szFile )  lSuccess
Parameters
Returns
FIL_close() : Closes a file.

Remark
FIL_close() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
FOCUS.FLL . The Opening Strategy controls how FOCUS.FLL is supposed to access files through low-level file
functions, either using the Win32 API or using the FoxPro API. One major disadvantage of the FoxPro API is that files
cannot be opened in a SHARE mode. The Opening Strategy is set to 2 by default (1=Win32 API; 2=FoxPro API). If the
Opening Strategy, at the time you call FIL_close() , is set to 2, FIL_close() will call the _FClose() FoxPro API
function; if it is set to 1 (Win32 API), FIL_close() will call the CloseHandle() Win32 service. A file that has been
opened with the Win32 API, cannot be accessed with the FoxPro API in subsequent calls.
Handles that are returned by the FIL_close() function when the Win32 API has been selected cannot be used by
low-level functions of FoxPro.
Syntax
FIL_close( nHandle )  lSuccess
Parameters
nHandle file handle.
Returns
lSuccess file closed successfully?
FIL_commit() : Flushes a file’s data buffer to disk.

Comment
When data is read from or written to disk, it is transferred through an area of memory known as a file buffer. The file
buffer setting can be positioned in the CONFIG.SYS file. Each buffer occupies 512 bytes of memory.
It is important to notice that buffers are a basic switch in speeding up PC operations when it comes to read and write
disks because the information can be accessed again later without having to actually read it from disk.

File Functions
This power comes at a price: when buffering disk writing, the information is not updated at the time the write is
performed. It is rather held in memory, up to the moment that the buffer is full, at which occasion it is physically
flushed. You can enforce writing thanks to FIL_commit() or FIL_FlushAll()
FIL_commit() is identical to FFLUSH() of Visual FoxPro. The function has been created to allow flushing data from
within FOCUS.FLL . Because it was available internally, we have decided to expose this function publicly.
FIL_commit() differs from FIL_FlushAll() in the sense that FIL_FlushAll() operates on streams.
Syntax
FIL_commit( nHandle )  lSuccess
Parameters
Returns
lSuccess file flushed successfully? .T. if operation was successful, .F. otherwise.
Example
LOCAL nHandle
nHandle = FCREATE( "C:\MYFILE" )
IF ( nHandle > 0 )
FWRITE( nHandle,"This is a test" )
IF ( ! FIL_commit( nHandle ) )
? "The file couldn't be flushed"
ENDIF
FCLOSE( nHandle )
ENDIF
See also
FIL_FlushAll() .
FIL_Common() : Compares two paths to determine if they

share a common prefix.
Alias
SHE_PathCommonPrefix() , FIL_PathCommonPrefix() .
Syntax
FIL_Common( szPath1,szPath2 )  szCommon
Parameters
szPath1 path to be compared with szPath2 .
szPath2 path to be compared with szPath1 .
Returns
szCommon common prefix.
Example
? FIL_common("C:\SPOT2100","C:\SPOT2100\MEMBERS") && " C:\SPOT2100"

File Functions
FIL_comp() : Reports if two files are the same.
Special
Under construction.
Alias
FileComp()
Syntax
FIL_comp( szFile1,szFile2 )  nDiff
Parameters
szFile1 file szFile1 will be compared to szFile2 .
szFile2 file szFile2 will be compared to szFile1 .
Returns
nDiff 0 if both files are identical. Otherwise nDiff indicates the first offset at which both files differ.
FIL_CompareTime() : Compares time and date stamps of two

files.
Syntax
FIL_CompareTime( szFile1,szFile2,nStructure )  nResult
Parameters
szFile1 first file.
szFile2 second file.
nStructure which structure should be examined. Time stamp type: 1 = LastWrite, 2 = LastAccess, 3 =
Creation
Returns
nResult can be 0, -1 or 1.
Value Meaning
-1 szFile1 is older than szFile2 .
0 szFile1 is equal to szFile2 .
1 szFile2 is older than szFile1 .
Example
* Comparing one file with itself will obviously result in 0
* (time is identical)
? FIL_CompareTime( "BOOKS.H","BOOKS.H",1 ) && 0
* Comparing a PRG file with its object module

? FIL_CompareTime( "BOOKS.PRG","BOOKS.FXP",1 ) && 1 (FXP older !)

File Functions
FIL_copy() : Copies a file.
Comment
Both MS-DOS and its upper Windows 16 bits layer were missing a fundamental function allowing to copy one file from
one place to another. Many programs or libraries did fill the gap by constructing routines to cover this basic service.
They did this by opening the source file source and creating a target file. Then, by filling up a buffer space, they
recopied the source file to the target file. Some did pay attention to the file and date stamps, some didn't.
The Win32 environment is now proposing a basic service called CopyFile() (simple enough...). Unfortunately, this
basic Win32 service does not provide an empty slot for a callback process so that there is no means to inform the
calling application of the file copy progression. The FIL_copy() function of FOCUS gives you the ability to use one or
the other method. Should you want to have a very quick copy (even in a kind of asynchronous mode), then we
recommend you to pass the FIL_copy() function an additional parameter: .T. . Should you feel that it's much
important to inform the user about the progression, then simply omit the fourth parameter of FIL_copy() .
Because, there is no way to determine whether you would prefer the target file date and time stamps to be related to
the copy or to the file source attributes, the FOCUS library does not use the date and time stamps of the source file. If
you want to keep these values, please use the FIL_gdate() , FIL_gtime() before copying and FIL_sdate() and
FIL_stime() functions after.
We have created two sample files: one is creating a progress bar of our own; the other uses the standard progress bar
of Windows 95. If you want to use the standard progress bar of Windows (which is by far the recommended method),
you can also use the additional service FIL_copyTimes() which will determine in advance how many times the
callback process is about to be triggered. The value returned by the FIL_copyTimes() function can then be used to
set the Max property of the progress bar. The second sample we have provided uses this method.
Alias
FCopy(), CopyFile(), FileCopy()
Syntax
FIL_copy( szFileIn,szFileOut[,szUDF[,lImmediate]] )  nSuccess
Parameters
szFileIn source file to be copied.
szFileOut destination file.
szUDF function to activate between each copy of a block. It is necessary to precede the function name
with a equal sign ("="). Do not include opening and closing parentheses. The function is passed
two parameters : the total number of blocks that must be copied and the current block number.
Optional parameter. Please notice that a copy without UDF is much faster than when mentioning
a function to execute.
lImmediate uses Windows to perform the copy (quickest way). Optional parameter.
Returns
nSuccess was the copy successful or not? 0 indicates a successful copy, -3 indicates that the source file
does not exist; -2 indicates that FIL_copy() was unable to open the source file, -1 indicates
that it was impossible to create the destination file.
When using the lImmediate parameter, 1 indicates a successful copy.
Example
* Very quick copy (using WIN32 CopyFile())
* Notice how the third parameter is passed with an empty string
? FIL_copy( "MYFILE.TXT","YOURFILE.TXT","",.T.)

File Functions
* Program Name: FIL_copy.prg
* Author: Pat Y. Boens
* Copyright (c) 1995 by The Technology DVL Group
* Created : 9 August 1995 at 22:21
*
*
* Revision number : 3.0 Last Revised : 23 September 1995 at 09:57
*
* Description : File copy synchronized with the a progress bar.
*
* The progress bar is the standard progress bar of
* Windows 95
#define GRAY RGB( 128,128,128,128,128,128 )

#define LIGHT_GRAY RGB( 192,192,192,192,192,192 )
#define GRAY_LIGHT RGB( 128,128,128,192,192,192 )
#define WHITE RGB( 255,255,255,255,255,255 )
#define BLACK RGB( 0,0,0,0,0,0 )
#define BACKGROUND RGB( ,,,192,192,192 )
#define BLACK_ON_WHITE RGB( ,,,255,255,255 )
#define NIL .NULL.
*----------------------------------------------------------------------*
LOCAL oFocus
oFocus = CREATEOBJECT( "FLL","FOCUS.FLL" )
IF ( oFocus.Load() )
=RunCopy()
ENDIF
*----------------------------------------------------------------------*
DEFINE CLASS FLL AS custom
FLLName = ""
Name = "FLL"
PROCEDURE Init( cFLL )
This.FLLName = cFLL
ENDPROC
*------------------------------------------------------------------*
PROCEDURE IsLoaded()
RETURN ( AT( UPPER( This.FLLName ),SYS( 2001,"LIBRARY" ) ) != 0 )
ENDPROC
*------------------------------------------------------------------*
PROCEDURE Load( lAdditive )

LOCAL cFLL
IF ( PARAMETERS() == 0 )
lAdditive = .F.
ENDIF
IF ( This.IsLoaded() )
RETU ( .T. )
ENDIF
WAIT WINDOW "Where is " + This.FLLName + "?" NOWAIT
cFLL = IIF( FILE( This.FLLName ), ;

This.FLLName , ;
GETFILE( "FLL" ) ;
)
IF ( EMPTY( cFLL ) ) && If library not found

File Functions
RETU ( .F. )
ELSE
This.FLLName = cFLL
IF ( lAdditive )
SET LIBRARY TO ( cFLL ) ADDITIVE
ELSE
SET LIBRARY TO ( cFLL )
ENDIF
RETU ( .T. )
ENDIF
ENDPROC
*------------------------------------------------------------------*
ENDDEFINE
*----------------------------------------------------------------------*
FUNCTION RunCopy()
oForm = CREATEOBJECT( "filecopy" )

oForm.Show
READ EVENTS
RETURN ( NIL )
*----------------------------------------------------------------------*
DEFINE CLASS filecopy AS form
Top = 104
Left = 40
Height = 98
Width = 480
DoCreate = .T.
BackColor = RGB( 192,192,192 )
Caption = "The Technology DVL Group (File copy sample)"
Icon = "devil.ico"
Name = "Form1"
ADD OBJECT ProgressBar AS olecontrol WITH ;

Top = 40 , ;
Left = 20 , ;
Height = 21 , ;
Width = 441 , ;
OLETypeAllowed = -2 , ;
OleClass = "COMCTL.ProgCtrl.1" , ;
Name = "ProgressBar"
PROCEDURE Activate()
LOCAL nTimes
nTimes = FIL_copyTimes( "DRAGDROP.PRG" )
IF ( nTimes > 0 )
ThisForm.ProgressBar.Max = nTimes
IF ( FIL_copy( "<whatever file> ", ;

"<your target> ", ;
"=Progress" ) == 0 )
WAIT WINDOW "Copy done !"
ELSE
WAIT WINDOW "Cannot copy file"
ENDIF
ELSE

File Functions
WAIT WINDOW "Cannot copy file : " + ALLTRIM(STR(nTimes))
ENDIF
ENDPROC
PROCEDURE Destroy()
ThisForm.Release
CLEAR EVENTS
ENDPROC
PROCEDURE ProgressBar.NextValue
IF ( ThisForm.ProgressBar.Value < ThisForm.ProgressBar.Max )
ThisForm.ProgressBar.Value = ThisForm.ProgressBar.Value + 1
ENDIF
ENDPROC
ENDDEFINE
*----------------------------------------------------------------------*
FUNCTION Progress( Total,n )
oForm.ProgressBar.NextValue()
RETURN ( NIL )
See also
FIL_copyTimes()
FIL_copyTimes() : Determines how many times the callback

function of FIL_copy() will be called.
Syntax
FIL_copyTimes( szFileIn )  nTimes
Parameters
szFileIn Source file to be copied.
Returns
nTimes Number of times the callback function of FIL_copy() is about to be called. A positive number
indicates that FIL_copy() can be called. In this case the callback process of FIL_copy() will
be called nTimes ; -3 indicates that the source file does not exist; -2 indicates that
FIL_copyTimes() was unable to open the source file.

File Functions
Example
See FIL_copy() .
See also
FIL_copy()
FIL_count() : Returns the number of files and directories that

match a particular specification.
Alias
FIL_FilesCount(), FIL_FileCount(), FilesCount(), FileCount()
Syntax
FIL_count( szFileSpec )  nFiles
Parameters
szFileSpec file specification. Ex. : "C:\MYDIR\*.*" . The function returns the number of files and
directories that match szFileSpec . The entries "." and ".." are disregarded by the
function.
Returns
nFiles Number of files that match the specification.
Example
FUNCTION IsEmptyDir( szDir )
RETURN ( FIL_count( szDir + "\*.*" ) == 0 )
FIL_create() : Creates a file.

Remark
FIL_create() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function
of FOCUS.FLL . The Opening Strategy controls how FOCUS.FLL is supposed to access files through low-level file
Opening Strategy, at the time you call FIL_create() , is set to 2, FIL_create() will call the _FCreate() FoxPro
API function; if it is set to 1 (Win32 API), FIL_create() will call the CreateFile() Win32 service. A file that has
been opened with the Win32 API, cannot be accessed with the FoxPro API in subsequent calls.
By placing a colon after the file name followed by a stream, this function makes it possible to access streams.
Alias
CreateFile(), FileCreate()
Syntax
FIL_create( szFile[,nAttributes[,nShareMode[,nFlags]]] )  nHandle
Parameters
szFile file name to be created.

File Functions
nAttributes file attributes. The meaning of this attribute is different depending you work with the Win32 API
or the FoxPro API.
Value Description
FoxPro API.
0 Read-Write
1 Read-Only
2 Hidden
3 Read-Only/Hidden
4 System
5 Read-Only/System
6 System/Hidden
7 Read-Only/Hidden/System
Win32 API
0x80000000 GENERIC_READ
0x40000000 GENERIC_WRITE
nShareMode share mode. This parameter is disregarded when the function is used in conjunction with the
FoxPro API.
Value Description
0x00000001 FILE_SHARE_READ
0x00000002 FILE_SHARE_WRITE
0x00000004 FILE_SHARE_DELETE
nFlags flags and attributes. This parameter is disregarded when the function is used in conjunction with
the FoxPro API.
Value Description
0x00000001 FILE_ATTRIBUTE_READONLY
0x00000002 FILE_ATTRIBUTE_HIDDEN
0x00000004 FILE_ATTRIBUTE_SYSTEM
0x00000010 FILE_ATTRIBUTE_DIRECTORY
0x00000020 FILE_ATTRIBUTE_ARCHIVE
0x00000080 FILE_ATTRIBUTE_NORMAL
0x00000100 FILE_ATTRIBUTE_TEMPORARY
0x00000800 FILE_ATTRIBUTE_COMPRESSED
0x00001000 FILE_ATTRIBUTE_OFFLINE
Returns
Example
#define WIN32_API 1
LOCAL szFile
LOCAL hFile
LOCAL OldStrategy
OldStrategy = FIL_SetOpenStrategy( WIN32_API )
hFile = FIL_create( "C:\MyFile.txt:MyStream",GENERIC_WRITE + GENERIC_READ )
IF ( hFile != -1 )
FIL_write( hFile,"This string won't appear in the file, but will in the stream" )
FIL_close( hFile )
ENDIF
FIL_SetOpenStrategy( OldStrategy )

File Functions
FIL_CreateHardLink() : Establishes an NTFS hard link between
an existing file and a new file. An NTFS hard link is similar
to a POSIX hard link.
Caution
This function does work ONLY in W2K, Win NT, and WinXP.
Remark
You can use the FIL_CreateHardLink() function to create hard links. A hard link is an NTFS-based link to a given
file. When you create a hard link to a file on an NTFS volume, NTFS adds a directory entry for the hard link without
duplicating the original file. By creating hard links, you can:
Create hard links that use the same file name as the original file but appear in different folders.
Create hard links that use different file names from the original file but appear in the same folder.
Create hard links that use different file names from the original file and appear in different folders.
Because a hard link is a directory entry for a file, an application can modify a file by using any of its hard links.
Applications that use any other hard link can detect the changes. However, directory entries for hard links are updated
only when a user accesses a file by using the hard link. For example, if a user opens and modifies a file by using its
hard link, and the size of the original file changes, the hard link that is used to access the file also shows the new size.
Syntax
FIL_CreateHardLink( szNewFile,szExistingFile )  lSuccess
Parameters
szNewFile new link to create
szExistingFile path to the existing file.
Returns
Example
* This example shows how you can refer to FOCUS.FLL with
* a common "Shared" version: this is the hard link
&& If the shared file does not exist ... create it!
IF ( ! FILE("D:\MY_SHARE_FOCUS.FLL" ) )
&& Try to create the link!!!

IF ( FIL_CreateHardLink( "D:\MY_SHARE_FOCUS.FLL","D:\MYAPP\FOCUS.FLL" ) )
&& This would be the common file

? FILE( "D:\MY_SHARE_FOCUS.FLL" ) && .T.
&& ... but the original file still exists
? FILE( "D:\MYAPP\FOCUS.FLL" ) && .T.
ENDIF
ENDIF

File Functions
FIL_crypt() : Encrypts a file.
Remark
The FIL_crypt() function is nice for quick encryption towards an End-User but does not provide a highly secured
scheme of encryption as any other user of FOCUS.FLL can decrypt the file thanks to FIL_decrypt() !
Alias
FIL_scramble()
Syntax
FIL_crypt( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn file to be encrypted.
szFileOut resulting file.
Returns
lSuccess file encrypted successfully?
Example
LOCAL nHandle
nHandle = FCREATE( "d:\manage2100\images2100\MYFILE.TXT")

FWRITE( nHandle,REPLICATE( "Hello, What's your name?",100))
FCLOSE(nHandle )
IF ( FIL_crypt( "d:\manage2100\images2100\MYFILE.TXT", ;
"d:\manage2100\images2100\MYFILE.CRYPT" ) )
? "The file was successfully crypted"
ENDIF
See also
FIL_decrypt()
FIL_decrypt() : Decrypts a file encrypted with FIL_crypt().

Alias
FIL_unscramble()
Syntax
FIL_decrypt( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn file to be decrypted.
szFileOut resulting file.
Returns
lSuccess file decrypted successfully?

File Functions
Example
IF ( FIL_decrypt( "d:\manage2100\images2100\MYFILE.CRYPT", ;
"d:\manage2100\images2100\MYFILE.TXT" ) )
? "The file was successfully decrypted"
ENDIF
See also
FIL_crypt()
FIL_del() : Deletes file or directory.

Alias
KillFile(), KillDir(), FIL_Delete(), DeleteFile()
Syntax
FIL_del( szFile )  lSuccess
Parameters
szFile file or directory to delete.
Returns
lSuccess file or directory successfully deleted?
Example
IF ( ! FIL_del( "C:\MYFILE.TXT" ) )
? "Attempt to delete file failed"
ENDIF
FIL_DeleteAll() : Deletes all file.

Alias
DeleteAll()
Syntax
FIL_DeleteAll( szFileSpec )  nDeleted
Parameters
szFileSpec file specification. Ex. : "C:\MYDIR\*.MSG" . Directories will not be deleted.
Returns
nDeleted number of files deleted.
Example
IF ( ! FIL_DeleteAll( "C:\MYDIR\*.TXT" ) )
? "Cannot delete all files"
ENDIF
FIL_drive() : Returns the drive letter from a complete path.

Syntax
FIL_drive( szPath )  szDrive

File Functions
Parameters
szPath path to extract drive qualifier from.
Returns
szDrive drive qualifier.
Example
? FIL_drive( "C:\DVL\FOX\FOCUS.FLL" ) && "C:"
FIL_exenam() : Returns the executable file name.

Remarks
The behavior of this function might be different given the environment. In the interpreted mode, this function returns
a string similar to "C:\VFP\VFP.EXE" . Executed from within a real .EXE file that has been produced with VFP, it
returns a string similar to "C:\MM.WIN\VFP300.ESL" . If you are interested in getting the real .EXE name, consider
using SYS(16,0) instead.
Alias
FIL_ExeName(), ExeName()
Syntax
FIL_exenam()  szExeName
Parameters
None.
Returns
szExeName name of the current executable.
Example
? FIL_exenam()
? SYS_exenam()
? SYS( 16,0 )
Alternatives
Try SYS(16,0) to get the real .EXE name.
See also
SYS_exenam() .
FIL_expand() : Expands a file.

Abstract
An application can decompress a single compressed file by performing the following tasks (in Win32API) :
1. Open the source file by calling the LZOpenFile() function.
2. Open the destination file by calling LZOpenFile() .

File Functions
3. Copy the source file to the destination file by calling the LZCopy() function and passing the handles returned
by LZOpenFile() .
4. Close the files by calling the LZClose() function.
In FOCUS.FLL , these tasks are all replaced by a single call to FIL_expand() .
Syntax
FIL_expand( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn source file to be expanded.
szFileOut target file.
Returns
lSuccess .T. if operation was successful; .F. if not.
Example
IF ( ! FIL_expand( "A:\NC_CORE.EX$","F:\NC_CORE.EXE" )
WAIT WINDOW "Error" NOWAIT
ENDIF
FIL_Explore() : Explores a specified folder.

Remark
FIL_explore() service is more specialized than SYS_ShellExecute() . It uses the same internal but passes it
many predefined parameters.
While FIL_explore( "Desktop" ) perfectly works with Windows 95, it does not work as it under Windows NT.
Syntax
FIL_Explore( cFolder )  nError
Parameters
cFolder folder to explore.
Returns
nError if the function succeeds, the return value is the instance handle of the application that was run,
or the handle of a DDE server application.
If the function fails, the return value is then less than or equal to 32.
Example
? FIL_Explore( "Desktop" )
? FIL_Explore( "C:\" )
See also
SYS_WinExec() , SYS_ShellExecute()

File Functions
FIL_ext() : Returns the three letter extension from a complete
path.
Special
This function is now superseded by FIL_split() . We still support it for backward compatibility, but we plan to drop
it soon.
Syntax
FIL_ext( szPath )  szFileExt
Parameters
szPath path to extract file extension from.
Returns
szFileExt file extension.
Example
? FIL_ext( "C:\DVL\FOX\FOCUS.FLL" ) && "FLL"
FIL_first() : Gets first instance of a filename that matches a

given file specification.
Syntax
FIL_first( szFileSpec )  szFile
Parameters
szFileSpec file specification string.
Returns
szFile first file that matches szFileSpec . Long filenames are returned by FIL_first() and
FIL_next() .
Example
szFile = FIL_first( "*.PRG" )
IF ( ! EMPTY( szFile ) )
DO WHILE ( ! EMPTY( szFile ) )
? szFile
szFile = FIL_next()
ENDDO
ENDIF
FIL_FlushAll() : Flushes all streams; clears all buffers.

Syntax
FIL_FlushAll()  nStreams
Parameters
None.

File Functions
Returns
nStreams number of open streams (input and output).
See also
FIL_commit() .
FIL_FndExe() : Find executable associated with a given

filename.
Alias
FIL_FindExe()
Syntax
FIL_fndexe( szFile,szDir )  szPath
Parameters
szFile filename. This file MUST exist.
szDir default directory.
Returns
szPath path in which the given executable was found.
Example
&& This example will determine what is the program associated to a PRG file
? FIL_FndExe( GETFILE("PRG"),"" ) && "d:\microsoft visual studio\vfp98\vfp6.exe"
FIL_FullName() : Returns the full path to a specified file.

Special
This function is not the opposite function of FIL_ShortName() .
Comment
If the full path name specifies parent directories
"C:\SAMPLES\ORGANIZE\..\FCOPY\..\ORGANIZE\CDROM.BMP" , by applying the FIL_FullName() function, it
will become ... "C:\SAMPLES\ORGANIZE\CDROM.BMP" .
Alias
FIL_LongName(), FIL_FullPath()
Syntax
FIL_FullName( szFile )  szFullPath
Parameters
szFile a file name.
Returns
szFullPath full pathname.

File Functions
Example
? FIL_FullName( ".\FOCUS.FLL" ) && "D:\INVOICES\FOCUS.FLL"
FIL_gdate() : Gets file date stamp.

Alias
GetFileDate(), FIL_GetFileDate(), FileDate()
Syntax
FIL_gdate( szFile,[nType] )  szDate
Parameters
szFile file whose date stamp has to be determined.
nType date stamp type : 1 = LastWrite, 2 = LastAccess, 3 = Creation. This parameter is optional. If
not specified FOCUS takes by default the LastWrite structure.
Returns
szDate file date stamp in the "YYYYMMDD" format. Use the DAT_stod() function to obtain a FoxPro
date.
Example
? FIL_gdate( "FOCUS.FLL" ) && "19950728"
See also
FIL_sdate(), FIL_gtime(), FIL_stime()
FIL_get() : Open File Dialog Box.

Comment
FIL_get() is somehow identical to FoxPro GETFILE() function. However it offers different control over the dialog
box : Title customization, Initial directory, multiple selection, etc.
Syntax
FIL_get( szFileSpec,szWinTitle,szInitialDir,nFlags )  szFile
Parameters
szFileSpec pairs of null-terminated filter strings. The first string in each pair describes a filter (for example,
szWinTitle window title.
szInitialDir initial directory.
#define OFN_READONLY 0x00000001

File Functions
#define OFN_OVERWRITEPROMPT 0x00000002
#define OFN_HIDEREADONLY 0x00000004
#define OFN_NOCHANGEDIR 0x00000008
#define OFN_SHOWHELP 0x00000010
#define OFN_ENABLEHOOK 0x00000020
#define OFN_ENABLETEMPLATE 0x00000040
#define OFN_ENABLETEMPLATEHANDLE 0x00000080
#define OFN_NOVALIDATE 0x00000100
#define OFN_ALLOWMULTISELECT 0x00000200
#define OFN_EXTENSIONDIFFERENT 0x00000400
#define OFN_PATHMUSTEXIST 0x00000800
#define OFN_FILEMUSTEXIST 0x00001000
#define OFN_CREATEPROMPT 0x00002000
#define OFN_SHAREAWARE 0x00004000
#define OFN_NOREADONLYRETURN 0x00008000
#define OFN_NOTESTFILECREATE 0x00010000
#define OFN_NONETWORKBUTTON 0x00020000
#define OFN_NOLONGNAMES 0x00040000
Following is an extract of the WIN32 API:
OFN_ALLOWMULTISELECT Specifies that the File Name list box allows multiple
selections. (If the dialog box is created by using a private
template, the definition of the File Name list box must contain
the LBS_EXTENDEDSEL value.)
OFN_CREATEPROMPT Specifies that the dialog box function should ask whether the
user wants to create a file that does not currently exist. (This
flag automatically uses the OFN_PATHMUSTEXIST and
OFN_FILEMUSTEXIST flags.)
OFN_ENABLEHOOK Enables the hook function specified in the lpfnHook member.
OFN_ENABLETEMPLATE Causes the operating system to create the dialog box by
using the dialog box template identified by hInstance and
lpTemplateName.
OFN_ENABLETEMPLATEHANDLE Indicates that hInstance identifies a data block that contains a
preloaded dialog box template. The operating system ignores
lpTemplateName if this flag is specified.
OFN_EXTENSIONDIFFERENT Specifies that the user typed a filename extension that differs
from the extension specified by lpstrDefExt. The function does
not use this flag if lpstrDefExt is NULL.
OFN_FILEMUSTEXIST Specifies that the user can type only names of existing files in
the File Name entry field. If this flag is specified and the user
enters an invalid name, the dialog box procedure displays a
warning in a message box. If this flag is specified, the
OFN_PATHMUSTEXIST flag is also used.
OFN_HIDEREADONLY Hides the Read Only check box
OFN_NOCHANGEDIR Causes the dialog box to set the current directory back to
what it was when the dialog box was called.
OFN_NONETWORKBUTTON Hides and disables the Network button.
OFN_NOREADONLYRETURN Specifies that the returned file does not have the Read Only
check box checked and is not in a write-protected directory.
OFN_NOTESTFILECREATE Specifies that the file is not created before the dialog box is
closed. This flag should be specified if the application saves
the file on a create-nonmodify network sharepoint. When an
application specifies this flag, the library does not check for
write protection, a full disk, an open drive door, or network
protection. Applications using this flag must perform file
operations carefully, because a file cannot be reopened once
it is closed.
OFN_NOVALIDATE Specifies that the common dialog boxes allow invalid
characters in the returned filename. Typically, the calling
application uses a hook function that checks the filename by
using the FILEOKSTRING message. If the text box in the edit
control is empty or contains nothing but spaces, the lists of
files and directories are updated. If the text box in the edit
control contains anything else, nFileOffset and nFileExtension
are set to values generated by parsing the text. No default
extension is added to the text, nor is text copied to the buffer
specified by lpstrFileTitle.

File Functions
If the value specified by nFileOffset is less than zero, the
filename is invalid. Otherwise, the filename is valid, and
nFileExtension and nFileOffset can be used as if the
OFN_NOVALIDATE flag had not been specified.
OFN_OVERWRITEPROMPT Causes the Save As dialog box to generate a message box if
the selected file already exists. The user must confirm
whether to overwrite the file
OFN_PATHMUSTEXIST Specifies that the user can type only valid paths and
filenames. If this flag is used and the user types an invalid
path and filename in the File Name entry field, the dialog box
function displays a warning in a message box.
OFN_READONLY Causes the Read Only check box to be checked initially when
the dialog box is created. This flag indicates the state of the
Read Only check box when the dialog box is closed.
OFN_SHAREAWARE Specifies that if a call to the OpenFile function fails because of
a network sharing violation, the error is ignored and the
dialog box returns the given filename. If this flag is not
specified, the registered message for SHAREVISTRING is sent
to the hook function with a pointer to a null-terminated string
for the path and filename in the lParam parameter.
Returns
szFile file(s) that has (have) been chosen.
Example
* Searching the current directory (normal interface)
? FIL_get( "Wave files" + CHR(0) + "*.WAV" + CHR(0) + ;
"FIL_get() interface" , ;
"." , ;
0 )
* Searching the Waves subdirectory allowing multiple selects

CURDIR() + "\WAVES" , ;
512 )

File Functions
* Searching the Waves subdirectory for *.WAV files or *.AVI

* files or *.* allowing multiple selects and get rid of the
* network button
"All files" + CHR(0) + "*.*" + CHR(0) + CHR(0) , ;
CURDIR() + "\WAVES" , ;
512 + 131072)
* Allowing to pick whatever file and then populate an editbox

* with all the files that were selected.
LOCAL szFiles AS String

LOCAL szOldSep AS String
LOCAL nTokens AS Integer
LOCAL szDir AS String
LOCAL i AS Integer
m.szFiles = FIL_get( "All files" + CHR(0) + "*.*" + CHR(0) + CHR(0), ;

"Choose attachments" , ;
CURDIR(),512 )
IF ( ! EMPTY( m.szFiles ) )
&& If multiple files have been selected, then we have a string that
&& is tokenized (" " being the separator).
&& The first token of the string is the directory from which the files
&& where selected. All the other tokens are the real files. Please
File Functions
&& notice that the function returns short filenames => a space
&& cannot occur in the middle of a name ... otherwise we would be
&& confused trying to extract each file with our token functions
m.szOldSep = STR_SetSep( " " )
&& Number of files = Number of tokens - 1 (1st token = source directory)

m.nTokens = STR_numtok( m.szFiles )
&& Extract 1st token (source directory)

m.szDir = STR_ntoken( 1,m.szFiles )
&& Empty the attachments (if any)

ThisForm.edtAttachments.value = ""
&& Extract from second token to before last token

FOR i = 2 TO m.nTokens – 1
ThisForm.edtAttachments.value = ThisForm.edtAttachments.value + ;
m.szDir + STR_ntoken( i,m.szFiles ) + ;
";"
NEXT
&& Extract last token

ThisForm.edtAttachments.value = ThisForm.edtAttachments.value + ;
m.szDir + STR_ntoken( m.nTokens,m.szFiles )
&& Reset the separators to what they were

STR_SetSep( m.szOldSep )
ENDIF
FIL_getatt() : Gets file attribute.

Syntax
FIL_getatt( szFile )  nAttribute
Parameters
Returns
nAttribute file attribute or -1 if error. Attribute values can be mixed.
Value (HEX) Description

00h Normal
01h Read-only
02h Hidden
04h System
08h Volume
10h SubDir
20h Archive
If function returns a value of 3, that means that the file is READ-ONLY ( 1) and is HIDDEN (2)
because 1 + 2 = 3
FIL_GetFolderLocation() : Obtains special folder location.

Comment
Certain folders have special meanings for the shell. An application can use shell functions to retrieve the locations of
these special folders and to enable the user to browse for specific folders.

File Functions
Some special folders are virtual folders—so called because they are not actual directories on any storage device, local
or remote. Virtual folders like the desktop folder, the My Computer folder, and the Network Neighborhood folder make
a unified namespace possible by serving as containers for any number of storage devices and network resources.
Other virtual folders contain file objects, such as printers, that are not part of the file system.
File system directories that the shell uses for specific purposes are also considered special folders. Examples include
the Programs folder (which contains the user's program groups) and the desktop directory (which is used to physically
store files that have been copied to the desktop folder). The locations of special file system folders are stored in the
registry under the HKEY_CURRENT_USER\Software\
Microsoft\Windows\CurrentVersion\Explorer\Shell Folders key.
You can use the SHGetSpecialFolderLocation() function to retrieve the location of a special folder, which can
be virtual or part of the file system. The function returns a PIDL, which the application must eventually free using the
shell's allocator. If the folder is part of the file system, you can convert the PIDL to a file system path by using the
SHGetPathFromIDList() function. The SHGetPathFromIDList() function converts an item identifier list to a file
system path :
WINSHELLAPI BOOL WINAPI SHGetPathFromIDList( LPCITEMIDLIST pidl ,
LPSTR pszPath
);
Parameters
pidl Pointer to an item identifier list that specifies a file or directory location relative to the root of the name
space (the desktop).
PszPath Pointer to a buffer that receives the file system path. The size of this buffer is assumed to be MAX_PATH
bytes.
Return Value
Returns TRUE if successful or FALSE if an error occurs, for example, if the location specified by the pidl parameter is
not part of the file system.
To display a dialog box that enables the user to browse for a folder, you can use the SHBrowseForFolder()
function. An application might use this function to prompt the user for a directory or remote computer. This function
can also be used to browse for network printers, even though printers are not considered folders. An application can
specify the root folder to browse from. For example, to prompt the user for a program group, you might call
SHBrowseForFolder() specifying the PIDL for the Programs folder as the root.
This function is the one you should use in order to locate the Recycle bin !
Syntax
FIL_GetFolderLocation( nFolderType )  szFullPath
Parameters
nFolderType folder type.
MANIFEST CONSTANT Value Description

CSIDL_DESKTOP 0x0000 Windows desktop – virtual folder at the root of
the name space.
CSIDL_PROGRAMS 0x0002 File system directory that contains the user's
program groups (which are also file system
directories).
CSIDL_CONTROLS 0x0003 Control Panel virtual folder containing icons for
the control panel applications.
CSIDL_PRINTERS 0x0004 Printers folder – virtual folder containing
installed printers.
CSIDL_PERSONAL 0x0005 File system directory that serves as a common
repository for documents
CSIDL_FAVORITES 0x0006 Favorites folder
CSIDL_STARTUP 0x0007 File system directory that corresponds to the
user's Startup program group.
CSIDL_RECENT 0x0008 File system directory that contains the user's
most recently used documents.
CSIDL_SENDTO 0x0009 File system directory that contains Send To
menu items.

File Functions
CSIDL_BITBUCKET 0x000a Recycle bin -- file system directory containing
file objects in the user's recycle bin. The
location of this directory is not in the registry;
it is marked with the hidden and system
attributes to prevent the user from moving or
deleting it.
CSIDL_STARTMENU 0x000b File system directory containing Start menu
items.
CSIDL_DESKTOPDIRECTORY 0x0010 File system directory used to physically store
file objects on the desktop (not to be confused
with the desktop folder itself)
CSIDL_DRIVES 0x0011 My Computer ¾ virtual folder containing
everything on the local computer: storage
devices, printers, and Control Panel. The
folder may also contain mapped network
drives.
CSIDL_NETWORK 0x0012 Network Neighborhood ¾ virtual folder
representing the top level of the network
hierarchy.
CSIDL_NETHOOD 0x0013 File system directory containing objects that
appear in the network neighborhood.
CSIDL_FONTS 0x0014 Virtual folder containing fonts.
CSIDL_TEMPLATES 0x0015 File system directory that serves as a common
repository for document templates.
Returns
szFullPath full pathname.
Example
? FIL_GetFolderLocation(2) && C:\WINDOWS\Start Menu\Programs
? FIL_GetFolderLocation(5) && C:\My Documents
FIL_gets() : Gets a string from a file.

Remark
FIL_gets() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_gets() , is set to 2, FIL_gets() will call the _FGets() FoxPro API
function; if it is set to 1 (Win32 API), FIL_gets() will call the ReadFile() and SetFilePointer() Win32
services. A file that has been opened with the Win32 API, cannot be accessed with the FoxPro API in subsequent calls.
Syntax
FIL_gets( nHandle,nBytes )  szLine
Parameters
nBytes optional number of bytes to read per line. By default, this parameter is set to 254.
Returns
szLine the line of text as it was read from the file.

File Functions
FIL_GetStdin() : Reads a number of characters from the
standard input (stdin).
Alias
FIL_stdin()
Syntax
FIL_GetStdin( nChars )  szString
Parameters
nChars number of characters to read from the standard input device. If there is no more character to
read from stdin BEFORE the function has read nChars characters, the function stops.
Returns
szString the characters read from stdin
See also
FIL_PutStdout()
FIL_GetTempFileName() : Creates a name for a temporary file.

The GetTempFileName() function creates a name for a temporary file. The filename is the concatenation of
specified path and prefix strings, a hexadecimal string formed from a specified integer, and the .TMP extension.
The specified integer can be nonzero, in which case, the function creates the filename but does not create the file. If
you specify zero for the integer, the function creates a unique filename and creates the file in the specified directory.
Syntax
FIL_GetTempFileName( szPathName , ;
szPrefixString, ;
nUnique )  szTempFileName
Parameters
szPathName points to a null-terminated string that specifies the directory path for the filename. This string
must consist of characters in the ANSI character set. Applications typically specify a period (.)
or the path where Windows is supposed to store temporary files.
szPrefixString points to a null-terminated prefix string. The function uses the first three characters of this
string as the prefix of the filename. This string must consist of characters in the ANSI character
set.
nUnique specifies an unsigned integer that the function converts to a hexadecimal string for use in
creating the temporary filename.
If nUnique is nonzero, the function appends the hexadecimal string to szPrefixString to

form the temporary filename. In this case, the function does not create the specified file, and
does not test whether the filename is unique.
If nUnique is zero, the function uses a hexadecimal string derived from the current system
time. In this case, the function uses different values until it finds a unique filename, and then it
creates the file in the szPathName directory.
The GetTempFileName() function creates a temporary filename of the following form :

path\preuuuu.TMP

File Functions
The following table describes the filename syntax:
Component Meaning
path Path specified by the szPathName parameter
pre First three letters of the cPrefixString string
uuuu Hexadecimal value of nUnique
When Windows shuts down, temporary files whose names have been created by this
function are not automatically deleted.
If the nUnique parameter is zero, GetTempFileName() attempts to form a unique number

based on the current system time. If a file with the resulting filename exists, the number is
increased by one and the test for existence is repeated. Testing continues until a unique
filename is found. GetTempFileName() then creates a file by that name and closes it. When
nUnique is nonzero, no attempt is made to create and open the file.
Returns
szTempFileName if the function succeeds, the return value is the name of the temporary file. Otherwise, the
function returns an empty string.
Remark
The string that is returned expresses the fullpath specification when tried on Windows 95. It returns a relative pathway
when it ran on Windows NT 4.0:
"D:\MEGA32\PAT8390.TMP" on Win95
".\PAT8390.TMP" on Win NT
Example
? FIL_GetTempFileName( ".","PAT",0 ) && "D:\MEGA32\PAT8390.TMP"
FIL_GetUniversalName() : Returns the Universal Name of a

mapped resource.
Comment
If the full path name specifies parent directories
"C:\SAMPLES\ORGANIZE\..\FCOPY\..\ORGANIZE\CDROM.BMP" , by applying the FIL_FullName() function, it
will become ... "C:\SAMPLES\ORGANIZE\CDROM.BMP" .
Alias
FIL_UniversalName(), GetUniversalName(), UniversalName(), NET_GetUniversalName(),
NET_GetConnection()
Syntax
FIL_GetUniversalName( szDrive )  szUniversal
Parameters
szDrive a mapped drive.
Returns
szUniversal universal resource name.
Example
&& Imagine for example that on the WebServer computer (machine name) there is
&& a SRCServer directory that is shared and accessible via the SRCServer Share Name.
&& Imagine this resource to be mapped to the E:\ drive. Then the FIL_GetUniversalName()

File Functions
&& function will return the UNC name (hence the name of the function) of this
&& resource.
? FIL_GetUniversalName( "E:\" ) && "\\WebServer\SRCServer"
FIL_gtime() : Gets file time stamp.

Alias
GetFileTime(), FIL_GetFileTime()
Syntax
FIL_gtime( szFile,[nType] )  cTime
Parameters
szFile file whose time stamp has to be determined.
nType time stamp type: 1 = LastWrite (default), 2 = LastAccess, 3 = Creation. This parameter is
optional. If not specified FOCUS takes by default the LastWrite structure.
Returns
cTime file time stamp.
Example
? FIL_gtime( "FOCUS.FLL" ) && "12:40:52"
See also
FIL_stime(), FIL_gdate(), FIL_sdate()
FIL_hleft() : Number of files that can still be open

simultaneously.
Caution
This function does not work for the time being. Under construction.
Syntax
FIL_hleft()  nFiles
Parameters
None.
Returns
nFiles remaining free handles.
FIL_iatime() : Last access to file,

FIL_ictime() : File creation time,
FIL_imtime() : Last file modification time.

File Functions
Comment
FIL_ictime() , FIL_imtime() and FIL_iatime() all return the same information because under DOS, the FAT
does not keep track of the file creation time, the last modification time and the last access time. However in other
environments this is not true. FOCUS for VFP is so fairly well adapted to Windows 95.
Syntax
FIL_i?time()  nTime
Parameters
None.
Returns
nTime the time is mentioned as Universal Coordinated Time. Make a call to either TIM_gmT() or
TIM_localT() to get a string result like "12:03:34"
Example
IF ( FIL_info( "AUTOEXEC.BAT" ) )
? "Creation time : ",TIM_localT( FIL_ictime() )
ENDIF
Caution
You first have to make a call to FIL_info() for this function to work properly.
FIL_ImmediateCopy() : Copies a file.

Syntax
FIL_ImmediateCopy( szSource,szTarget,lFailIfExist )  lSuccess
Parameters
szSource existing file to be copied to szTarget .
szTarget filename to copy to.
lFailIfExist flag for operation if file exists. If this parameter is .T. and the new file already exists, the
function fails. If this parameter is .F. and the new file already exists, the function overwrites
the existing file and succeeds.
Returns
lSuccess .T. if copy is successful; .F. if not.
FIL_info() : Obtains general information about a file.

Syntax
FIL_info( szFile )  lSuccess
Parameters
szFile file for which you want to get information.

File Functions
Returns
Upon return, an internal structure of FOCUS is updated. You can query information from this
structure with other functions like FIL_isize() , FIL_imtime() , FIL_iatime() , and
FIL_ictime() .
Example
? "Creation time : ",FIL_ictime()
? "Last modification time : ",FIL_imtime()
? "File size : ",FIL_isize()
ENDIF
FIL_IsArchived() : Is the given file an archived file?

Syntax
FIL_IsArchived( szFile )  lStatus
Parameters
szFile file name.
Returns
lStatus .T. if file is archived; .F. otherwise.
FIL_isbof() : Is given file at BOF position?

Syntax
FIL_isbof( nHandle )  lStatus
Parameters
Returns
lStatus is the given file at Begin Of File position?
Example
LOCAL nHandle
nHandle = FOPEN( "MYFILE.TXT" )
? FIL_isbof( nHandle ) && .T.

FSEEK( nHandle,0,2 ) && Move file pointer to end of file
? FIL_isbof( nHandle ) && .F.
FCLOSE( nHandle )
FIL_IsCompressed() : Is the given file a compressed file?

Remark
This function determines if the file is compressed by the Operating System, not thanks to a tool such as a ZIP utility.

File Functions
Syntax
FIL_IsCompressed( szFile )  lStatus
Parameters
szFile file name.
Returns
lStatus .T. if file is a compressed file; .F. otherwise.
FIL_IsDirectory() : Tests whether a file is marked with a

directory flag.
Syntax
FIL_IsDirectory( szFile )  lIsDir
Parameters
szFile the directory to check for existence.
Returns
lIsDir .T. if file is marked with directory flag; .F. otherwise.
FIL_isEOF() : Is given file at EOF position?

Remark
FIL_isEOF() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_isEOF() , is set to 2, FIL_isEOF() will call the _FSeek() FoxPro API
function; if it is set to 1 (Win32 API), FIL_isEOF() will call the SetFilePointer() Win32 service. A file that has
Syntax
FIL_iseof( nHandle )  lStatus
Parameters
Returns
lStatus is the given file at End Of File position?
Example
LOCAL nHandle
nHandle = FOPEN( "MYFILE.TXT" ) && Let’s imagine that file

&& contains 100 bytes
? FIL_iseof( nHandle ) && .F.

FSEEK( nHandle,0,2 ) && Move file pointer to end of file
? FIL_iseof( nHandle ) && .T.
FCLOSE( nHandle )

File Functions
FIL_IsFile() : Determines if the specified file exists.
Syntax
FIL_IsFile( szFile )  lSuccess
Parameters
szFile the file whose existence has to be checked.
Returns
lSuccess .T. if file exists; .F. if not.
FIL_IsHidden() : Is the given file hidden?

Syntax
FIL_IsHidden( szFile )  lStatus
Parameters
szFile file name.
Returns
lStatus .T. if file is hidden; .F. otherwise.
FIL_isize() : Gets file size.

Syntax
FIL_isize()  nSize
Parameters
None.
Returns
nSize file size in bytes.
Example
? "File size : ",FIL_isize(),"bytes"
ENDIF
Caution
You first have to make a call to FIL_info() for this function to work properly.
FIL_IsNormal() : Is the given file a normal file?

Syntax
FIL_IsNormal( szFile )  lStatus

File Functions
Parameters
szFile file name.
Returns
lStatus .T. if file is normal; .F. otherwise.
FIL_IsReadOnly() : Is the given file read only?

Syntax
FIL_IsReadOnly( szFile )  lStatus
Parameters
szFile file name.
Returns
lStatus .T. if file is the read only mode; .F. otherwise.
FIL_IsShared() : Is the given directory shared?

Alias
FIL_IsDirShared()
Syntax
FIL_IsShared( szDir )  lStatus
Parameters
szDir directory name.
Returns
lStatus .T. if file is a shared directory; .F. otherwise.
Example
? FIL_IsShared( "D:\INVOICES" ) && .F.
? FIL_IsShared( "C:\" ) && .T.
FIL_IsShortcut() : Is a given file object a shortcut?

Syntax
FIL_IsShortcut( szFile )  lShortcut
Parameters
szFile file object name.
Returns
lShortcut .T. if file is a shortcut; .F. otherwise.

File Functions
Example
? FIL_IsShortcut( "C:\Documents and Settings\Pat Boens\Desktop\CDPlayer.lnk" ) && .T.
FIL_IsSystem() : Is the given file a system file?

Syntax
FIL_IsSystem( szFile )  lStatus
Parameters
szFile file name.
Returns
lStatus .T. if file is a system file; .F. otherwise.
FIL_IsTmp() : Is the given file a temporary file?

Syntax
FIL_IsTmp( szFile )  lStatus
Parameters
szFile file name.
Returns
lStatus .T. if file is a temporary file; .F. otherwise.
FIL_isUNC() : Determines if the string is a valid UNC (universal

naming convention) for a server and share path.
Syntax
FIL_IsUNC( szPath )  lIsUNC
Parameters
szPath path to consider.
Returns
lIsUNC .T. if szPath is a valid UNC path; .F. otherwise.
FIL_LastVersion() : Returns the file stamp of FIL functions.

Remark
Syntax
FIL_LastVersion()  szLastVersion

File Functions
Parameters
None.
Returns
"C:\Focus\5.0\FILES.C-Mon Oct 19 15:55:22 1998" .
FIL_len() : Determines the length of an open file.

Remark
FIL_len() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_len() , is set to 2, FIL_len() will call the _FSeek() FoxPro API
function; if it is set to 1 (Win32 API), FIL_len() will call the SetFilePointer() Win32 service. A file that has
Handles that are returned by the FIL_open() function when the Win32 API has been selected cannot be used by
low-level functions of FoxPro such as FWRITE() , FCLOSE() and the likes.
FIL_len() and FIL_size() are identical from the functionality point of view although they're using very different
methods to determine a file's size. The first one operates on a handle, while the second one operates with a filename.
Syntax
FIL_len( nHandle )  nSize
Parameters
Returns
nSize size of file in bytes.
Example
LOCAL nHandle
LOCAL OldStrategy
OldStrategy = FIL_SetOpenStrategy( 2 )
nHandle = FOPEN( "C:\TEST.PRG" )
? FIL_len( nHandle )
FCLOSE( nHandle )
FIL_SetOpenStrategy( OldStrategy )
See also
FIL_size() .

File Functions
FIL_LenCompressed() : Obtains the compressed size, in bytes,
of a specified file.
Remark
The FIL_LenCompressed() function obtains the actual number of bytes of disk storage used to store a specified
file. If the file is located on a volume that supports compression, and the file is compressed, the value obtained is the
compressed size of the specified file. If the file is not located on a volume that supports compression, or if the file is
not compressed, the value obtained is the actual file size.
Syntax
FIL_LenCompressed( szFile )  nLength
Parameters
szFile file name to determine the length of.
Returns
nLength length of the file.
Example
IF ( ! FIL_SetCompression( "MYFILE.TXT",.T. ) )
WAIT WINDOW "Cannot compress file"
ELSE
&& Displays the length of the file (compressed size)
? FIL_LenCompressed( "MYFILE.TXT" )
ENDIF
See also
FIL_IsCompressed(), FIL_SetCompression(), FIL_len()
FIL_mkdir() : Creates a directory

Syntax
FIL_mkdir( szDir )  lSuccess
Parameters
szDir directory to create.
Returns
Example
IF ( ! FIL_mkdir( "Hello World" ) )
? "Directory creation failed."
ENDIF
FIL_name() : Returns the file name from a complete path.

Syntax
FIL_name( szPath )  szFile

File Functions
Parameters
szPath path to extract file name from.
Returns
szFile file name.
Example
? FIL_name( "C:\DVL\FOX\FOCUS.FLL" ) && "FOCUS"
FIL_next() : Gets next instance of a filename that matches a

given file specification (see FIL_first()).
Syntax
FIL_next()  szFile
Parameters
None.
Returns
szFile next instance. Long filenames are returned by FIL_first() and FIL_next() .
Example
szFile = FIL_first( "*.PRG" )
IF ( ! EMPTY( szFile ) )
? szFile
szFile = FIL_next()
ENDDO
ENDIF
FIL_now() : Returns a file name in the

YYYYMMDDHHmmSSXXXXXXXXXX format.
Remark
FIL_now() makes it possible to determine a filename that corresponds to the NOW moment. YYYY stands for the
year, MM for the month, DD for the day, HH for the hour, mm for the minutes, SS for the seconds, and
XXXXXXXXXX for the tick count (the tick count is left padded with "0").
FIL_now() makes it very easy to get a filename that is most likely to be unique (although strictly speaking a file with
the same name might already be existing) and that can be used to store sequential information. For example, each
time that a log file is internally compressed by the LOG_*() functions of FOCUS, the resulting file is named by a call
to FIL_now() .
FIL_now() does not create any file but the FIL_CreateNow() does!
Alias
FIL_CreateNow(), TIM_now(), DAT_now(), STR_now(), Now()
Syntax
FIL_now()  szFile
FIL_CreateNow( szDir )  szFile
File Functions
Parameters
szDir FIL_now() takes no parameter but its alias FIL_CreateNow() does. szDir indicates the
directory where the NOW file has to be created. In the case of the FIL_CreateNow()
function/alias, the file is also created under the szDir directory. It should be noted that the
FIL_CreateNow() always adds a backslash at the end of szDir before concatenating it with
szFile .
Returns
szFile resulting filename. The FIL_CreateNow() function gets the full path spec or an empty string
if the file couldn't be created. If the file was already existing, it is overwritten.
Example
? FIL_now() && "199810291721330030346194"
? FIL_CreateNow( "C:"
FIL_open() : Opens a file in a given mode.

Remark
FIL_open() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_open() , is set to 2, FIL_open() will call the _FOpen() FoxPro API
function; if it is set to 1 (Win32 API), FIL_open() will call the CreateFile() Win32 service. A file that has been
Handles that are returned by the FIL_open() function when the Win32 API has been selected cannot be used by
low-level functions of FoxPro.
By placing a colon after the file name followed by a stream, this function makes it possible to access streams.
Alias
OpenFile(), FileOpen()
Syntax
FIL_open( szFile,nFlag,nShareMode )  nHandle
Parameters
szFile file name to be opened.
nFlag the meaning of this parameter is different based on the API that's about to be used.
Value Description
FoxPro API.
0 Read Only
1 Write Only
2 Read Write
Win32 API
0x80000000 GENERIC_READ
0x40000000 GENERIC_WRITE
nShareMode this parameter is disregarded when used in conjunction with the FoxPro API.
Value Description

File Functions
0x00000001 FILE_SHARE_READ
0x00000002 FILE_SHARE_WRITE
Returns
FIL_OpenFile() : Attempts to open a file in SHARED mode. The

file is closed upon exit of the function.
Remark
The FIL_OpenFile() function can be used to try to open a given file in SHARED mode. If it can, it closes the file and
returns a .T. value; if it cannot, it simply returns a .F. value.
With this function you can actually test if there is a reasonable chance to open a file in SHARED mode. If there is, you
can then try to open it with USE <dbf> . Of course, nothing is preventing other programs from opening the file in
EXCLUSIVE mode between the moment you issue the FIL_OpenFile() function and the moment you will execute
the USE <dbf> command. That's the reason why we speak about a reasonable chance.
Syntax
FIL_OpenFile( szFile )  lSuccess
Parameters
szFile file to open in SHARED mode (SHARED read, and SHARED write).
Returns
lSuccess .T. if we successfully opened the file; .F. if not.
Example
IF ( FIL_OpenFile( "C:\DATA\MY.DBF" ) )
USE "C:\DATA\MY.DBF" SHARED
ELSE
? "Cannot open C:\DATA\MY.DBF"
ENDIF
FIL_owner() : Finds the owner of a given file.

Special
This function will only work under Windows NT and Windows XP.
Syntax
FIL_Owner( szFile )  szOwner
Parameters
szFile file to consider.
Returns
szOwner owner of the file.

File Functions
Example
LOCAL szOwner
m.szOwner = FIL_Owner( "C:\DATA\MY.DBF" )
IF ( ! EMPTY( m.szOwner ) )
? "The owner of the file is",m.szOwner
ELSE
? "Cannot obtain owner name:",FIL_LastError()
ENDIF
FIL_path() : Returns the pathname from a complete path.

Syntax
FIL_path( szPath )  szPath
Parameters
szPath the full path to extract the pathname from.
Returns
szPath path.
Example
? FIL_path( "C:\DVL\FOX\FOCUS.FLL" ) && "C:\DVL\FOX"
FIL_puts() : Writes a string plus a carriage return line feed pair

to a file.
Remark
FIL_puts() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_puts() , is set to 2, FIL_puts() will call the _FPuts() FoxPro API
function; if it is set to 1 (Win32 API), FIL_puts() will call the WriteFile() Win32 service. A file that has been
Syntax
FIL_puts( nHandle,szString )  nBytes
Parameters
szString string to write to the file.
Returns
nBytes number of bytes written to the file.

File Functions
FIL_PutStdout() : Outputs a string to the standard output
device (stdout).
Alias
FIL_stdout()
Syntax
FIL_PutStdout( szString )  lSuccess
Parameters
szString the string to output to the standard output device.
Returns
lSuccess .T. if szString was successfully output to the standard output; .F. if not.
See also
FIL_GetStdin()
FIL_read() : Returns a specified number of bytes.

Remark
FIL_read() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_read() , is set to 2, FIL_read() will call the _FRead() FoxPro API
function; if it is set to 1 (Win32 API), FIL_read() will call the ReadFile() Win32 service. A file that has been
Syntax
FIL_read( nHandle,nBytes )  szData
Parameters
nBytes number of bytes to read.
Returns
szData the data as it was read from the file. If the file couldn't be read, the function returns an empty
string.
FIL_ReadAllSections() : Reads all the sections of any INI file.

Alias
GetPrivateProfileSections(),GetPrivateProfileSectionNames()
Syntax
FIL_ReadAllSections( szIniFile )  szSections

File Functions
Parameters
szIniFile .INI file name.
Returns
szSections all sections of the .INI file. Sections are separated by each other with a semicolon (";").
See also
FIL_sectio()
FIL_ReadSub() : Reads a number of bytes from as specific

location in a file.
Remark
FIL_ReadSub() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function
of FOCUS.FLL . The Opening Strategy controls how FOCUS.FLL is supposed to access files through low-level file
Opening Strategy, at the time you call FIL_ReadSub() , is set to 2, FIL_ReadSub() will call the _FRead() FoxPro
API function; if it is set to 1 (Win32 API), FIL_ReadSub() will call the ReadFile() Win32 service. A file that has
been opened with the Win32 API, cannot be accessed with the FoxPro API in subsequent calls before the file is closed.
Syntax
FIL_ReadSub( nHandle,nStart,nBytes )  szData
Parameters
nStart starting position to read from. The first position in the file is 1.
nBytes number of bytes to read.
Returns
szData the data as it was read from the file. If the file couldn't be read, the function returns an empty
string.
FIL_ReadWININIAllSections() : Reads all the sections of the

WIN.INI file.
Syntax
FIL_ReadWININIAllSections()  szSections
Parameters
None.
Returns
szSections a buffer with all sections separated with a ";" .

File Functions
FIL_reaini() : Reads a character string from an .INI file.
Alias
FIL_ReadIni() , GetPrivateProfileString()
Syntax
FIL_reaini( szSection,szEntry,szIniFile )  szValue
Parameters
szSection section of .INI file.
szEntry key name that appears under the section name.
Returns
szValue string pertaining to entry.
Example
IF ( FIL_reaini( "SECRET","PassWord","MY.INI" ) != szPassWord )
? "Wrong password !"
ENDIF
FIL_rename() : Renames a given file.

Comment
On a Case Sensitive File System, you'll have to make sure that case is exactly preserved. Under Windows 95 (by
default, the system preserves case sensitivity (SYS_IsFileCasePreserved() ) but does not pay attention to cases
(SYS_IsFileCaseSensitive() )), renaming a file is no innocent operation.
Syntax
FIL_rename( szSource,szTarget )  lSuccess
Parameters
szSource file name to rename.
szTarget new file name.
Returns
lSuccess operation successful or not?
Example
&& Under Windows 95 this code will change the case
&& of the file. If the exact filename was "Test.c", it will
&& now be changed to "TEST.C"
IF ( FIL_rename( "C:\TEST.C","C:\TEST.C") )
? "File renamed successfully"
ELSE
? "Operation failed"
ENDIF
&& Other example

File Functions
? FIL_rename( "D:\CSERVE\DOWNLOAD\FORUMS\ALL MICROSOFT FORUMS ON COMPUSERVE",;
"D:\CSERVE\DOWNLOAD\FORUMS\All Microsoft forums on CompuServe" )
FIL_rendir() : Renames a given file or directory.

Syntax
FIL_rendir( szSource,szTarget )  lSuccess
Parameters
szSource file name or directory name to be renamed.
szTarget new file name or new directory name.
Returns
Example
IF ( FILE( szToBeSaved ) )
? "This file already exists. Do you want to rename it?"
m.lAnswer = MIS_yesno()
IF ( m.lAnswer )
ACCEPT "Enter new file name" TO szNewName
IF ( ! FIL_rendir( szToBeSaved,szNewname ) )
? "Attempt to rename file failed !"
ENDIF
ENDIF
ENDIF
See also
FIL_del() , FIL_rename() , FIL_rmdir() .
FIL_rmdir() : Removes a directory.

Syntax
FIL_rmdir( szPath )  lSuccess
Parameters
szPath directory to be removed.
Returns
Example
IF ( ! FIL_rmdir( "C:\DVL" ) )
? "Cannot remove directory. Check if empty."
ENDIF
See also
FIL_del() , FIL_rename() , FIL_rendir() .

File Functions
FIL_save() : Save File Dialog Box.
Syntax
FIL_save( szFile,szTitle,szDir,nFlags )  szFile
Parameters
szFile pairs of null-terminated filter strings. The first string in each pair describes a filter (for example,
szTitle window title.
szDir initial directory.
nFlags dialog box flags. Please refer to the values described for the FIL_get() function.
Returns
szFile file that has been chosen.
Example
* Saving a file
? FIL_save( "Wave files" + CHR(0) + "*.WAV" + CHR(0) + ;
"Mention your file" , ;
"." , ;
0 )

File Functions
FIL_sdate() : Sets file date stamp.
Alias
SetFileDate(), FIL_SetFileDate()
Syntax
FIL_sdate( szFile,szDate,[nType] )  lSuccess
Parameters
szFile file whose date stamp has to be set.
szDate date stamp string in the "YYYYMMDD" format.
nType date stamp type: 1 = LastWrite, 2 = LastAccess, 3 = Creation. This parameter is optional. If not
specified FOCUS takes by default the LastWrite structure.
Returns
Example
? FIL_sdate( "MYFILE.TXT",DTOS( DATE() ),1 ) && .T.
See also
FIL_gdate(), FIL_gtime(), FIL_stime()
FIL_sectio() : Reads .INI section.

Syntax
FIL_sectio( szSection,szINIFile )  szEntries
Parameters
szSection section to read.
szINIFile .INI file to read from.
Returns
szEntries all entries for given section. Up to 1024 bytes. Each entry is separated by a ";".
Example
? "Wallpaper settings",FIL_sectio( "wallpaper","myapp.ini" )
See also
FIL_ReadAllSections()
FIL_seek() : Moves the file pointer to a new position.

Remark
FIL_seek() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of

File Functions
Opening Strategy, at the time you call FIL_seek() , is set to 2, FIL_seek() will call the _Fseek() FoxPro API
function; if it is set to 1 (Win32 API), FIL_seek() will call the SetFilePointer() Win32 service. A file that has
Syntax
FIL_seek( nHandle,nOffset,nStrategy )  nPosition
Parameters
nHandle file handle as returned by the FIL_open() function..
nOffset new position in file.
nStrategy relative position.
Value Description
0 The pointer is moved relative to the beginning of the file
1 The pointer is moved relative to the current position in the file.
2 The pointer is moved relative to the end of the file
Returns
nPosition number of bytes the file pointer is positioned from the beginning of the file.
See also
FIL_IsEOF() , FIL_IsBOF() , FIL_SetOpenStrategy()
FIL_SetArchived() : Sets the Archive attribute of a file.

Syntax
FIL_SetArchived( szFile )  lSuccess
Parameters
Returns
FIL_setatt() : Sets file attribute.

Syntax
FIL_setatt( szFile,nAttribute )  lSuccess
Parameters
nAttribute new attribute of file.

File Functions
Value Description
(HEX)
00h Normal
01h Read-only
02h Hidden
04h System
08h Volume
10h SubDir
20h Archive
Attribute values can be mixed.
Returns
Example
Here is an example for hiding a file
FIL_setatt( "MYFILE.CFG",2 )
* Here is an example for making a file READ-ONLY

* Here is an example for making a file HIDDEN and READ-ONLY

FIL_SetCompressed() : Sets the Compressed attribute of a file.

Syntax
FIL_SetCompressed( szFile )  lSuccess
Parameters
Returns
FIL_sethan() : Allocates file handles to the current process.

Alias
FIL_SetHandleCount()
Comment
The FIL_sethan() function is not necessary under the Windows NT implementation of Win32.
The FIL_sethan() function may be necessary under other implementations of Win32, such as Win32s, in order to
increase the default number of available file handles. Under Win32s, this default is 20.
Internal Call
SetHandleCount()
Syntax
FIL_sethan( nHandles )  nHandlesSet

File Functions
Parameters
nHandles specifies the number of file handles needed by the application. The maximum value is
implementation-dependent. Under Win32s, the maximum value is 255 .
Returns
nHandlesSet under Win32s, the return value specifies the number of file handles actually available to the
application. It may be fewer than the number specified by the nHandles parameter.
Example
IF ( FIL_sethan( 65 ) < 65 )
? "You must free file handles to run this application."
ENDIF
FIL_SetHidden() : Sets the Hidden attribute of a file.

Syntax
FIL_SetHidden( szFile )  lSuccess
Parameters
Returns
FIL_SetNormal() : Sets the Normal attribute of a file.

Syntax
FIL_SetNormal( szFile )  lSuccess
Parameters
Returns
FIL_SetCompression() : Compresses a file.

Remark
This function can be used on files and directories. The volume must support compression, like in Windows NT.
Syntax
FIL_SetCompression( szFile,lCompression )  lSuccess
Parameters
szFile file name.
lCompression .T. to compress file; .F. to decompress file.

File Functions
Returns
lSuccess operation was successful or not.
Example
IF ( ! FIL_SetCompression( "MYFILE.TXT",.T. ) )
WAIT WINDOW "Cannot compress file"
ELSE
&& Displays the length of the file (compressed size)
? FIL_LenCompressed( "MYFILE.TXT" )
ENDIF
See also
FIL_IsCompressed(), FIL_LenCompressed(), FIL_len()
FIL_SetOpenStrategy() : Determines how the low-level

functions of FOCUS will access files.
Alias
FIL_GetOpenStrategy()
Syntax
FIL_SetOpenStrategy( [nStrategy] )  nCurrentStrategy
Parameters
nStrategy strategy to use (1=Win32 API; 2=FoxPro API). This parameter is optional. When it is not
passed, the function simply returns the current status. When you use the
FIL_GetOpenStrategy() , this parameter may not be passed along.
Returns
nCurrentStrategy current strategy as it was set prior to enter in the function.
Example
LOCAL nHandle
LOCAL nStrategy
******************************************************************
* The following example opens a file thanks to the Win32 API, and
* reads each line of text and displays it.
******************************************************************
#define STRA_WIN32API 1
#define STRA_FOXPROAPI 2

#define FILE_SHARE_READ 0x00000001
#define FILE_SHARE_WRITE 0x00000002
#define INVALID_HANDLE -1
nStrategy = FIL_SetOpenStrategy( STRA_WIN32API )
nHandle = FIL_open( "MYFILE.TXT" , ;

GENERIC_READ + GENERIC_WRITE, ;
FILE_SHARE_READ + FILE_SHARE_WRITE )
IF ( nHandle != INVALID_HANDLE )
DO WHILE ( ! FIL_iseof( nHandle ) )
? FIL_gets( nHandle )
ENDDO
FIL_close( nHandle )

File Functions
ENDIF
&& Restore the Strategy to what it was prior entering this function
FIL_SetOpenStrategy( nStrategy )
FIL_SetReadOnly() : Sets the Read-Only attribute of a file.

Syntax
FIL_SetReadOnly( szFile )  lSuccess
Parameters
Returns
FIL_SetSystem() : Sets the System attribute of a file.

Syntax
FIL_SetSystem( szFile )  lSuccess
Parameters
Returns
FIL_SetTmp() : Sets the Temporary attribute of a file.

Syntax
FIL_SetTmp( szFile )  lSuccess
Parameters
Returns
FIL_ShortName() : Obtains the short name equivalent of a

filename.
Syntax
FIL_ShortName( szFile )  cShortName
Parameters
szFile long filename to be transformed.

File Functions
Returns
cShortName short form of <szFile> .
Example
&& We emphasized in bold the long pathname part
szPath = "D:\CSERVE\DOWNLOAD\MICROSOFT FORUMS\FORUMS.TXT"
szShortName = FIL_ShortName( szPath )

&& Returns something like :
&& "D:\CSERVE\DOWNLOAD\MICROS~1\FORUMS.TXT"
FIL_size() : Determines the length of a file.

Remark
FIL_len() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
FOCUS.FLL . This is not the case of the FIL_size() function that operates through the use of a filename instead of a
handle. Starting with version 6.0 of FOCUS.FLL the FIL_size() function can even operate on files that are already
opened. That wasn't the case before.
Syntax
FIL_size( szFile )  nSize
Parameters
szFile file name.
Returns
nSize size of file in bytes.
See also
FIL_len() .
FIL_slices() : Cuts a file into several slices of a given size.

Syntax
FIL_slices( szFile,nSize )  nSlices
Parameters
szFile file to cut into smaller slices.
nSize size of each slice.
Returns
nSlices number of slices used (= FileSize / nSliceSize + 1 ). The output files are named
OUTPUT.1 , OUPUT.2 , ... up to OUTPUT.<nSlices> . These OUPUT files are created in the
current directory. The function is very useful when you need to cut a file to be duplicated on
several floppy disks.
Example
&& This example is supposed to divide the BIGFILE.ZIP file
&& into different smaller files, each of 200000 bytes, except
&& the last one that may be smaller (rest of the file)

File Functions
&& Then, it displays whether the supposed OUTPUT files
&& exist or not
nSlices = FIL_slices( "BIGFILE.ZIP",200000 )
FOR i = 1 TO nSlices
? FILE( "OUTPUT." + ALLTRIM( STR( i ) ) )
NEXT
FIL_split() : Splits full filename into their basic components.

Alias
SplitPath()
Syntax
FIL_split( szFile,nComponent )  szComponent
Parameters
szFile filename to split.
nComponent component number to return.
Value Description
1 Drive
2 Directory
3 Filename without the extension
4 Extension including the dot separator
Returns
szComponent appropriate file component.
Example
? FIL_split( "C:\DVL\FOCUS.FLL",1 ) && "C:"
? FIL_split( "C:\DVL\FOCUS.FLL",2 ) && "\DVL\"
? FIL_split( "C:\DVL\FOCUS.FLL",3 ) && "FOCUS"
? FIL_split( "C:\DVL\FOCUS.FLL",4 ) && ".FLL"
FIL_stime() : Sets file time stamp.

Alias
SetFileTime(), FIL_SetFileTime()
Syntax
FIL_stime( szFile,szTime,[nType] )  lSuccess
Parameters
szFile file whose time stamp has to be set.
szTime time stamp string in the "HH:MM:SS" format.
nType time stamp type: 1 = LastWrite, 2 = LastAccess, 3 = Creation. This parameter is optional. If not
specified FOCUS.FLL takes by default the LastWrite structure.
Returns

File Functions
Example
? FIL_stime( "MYFILE.TXT","03:00:00",1 ) && .T.
See also
FIL_sdate(), FIL_gdate(), FIL_gtime()
FIL_StringToFile() : Writes a string to a file.

Syntax
FIL_StringToFile( szFile,szString )  lSuccess
Parameters
szFile file in which will be written (the file is ALWAYS created).
szString string to write to szFile .
Returns
Example
&& Example #1
? FIL_StringToFile( "C:\MYFILE.TXT","This is the text" )
&& Example #2
LOCAL szWeb
LOCAL szNum
LOCAL szExt
&& This example will extract an image from FastWrite's web site. The image is
&& returned as a string. Then, the string is saved to a file thanks to
&& FIL_StringToFile() and finally, the background picture of VFP is set to the
&& newly created image file
szWeb = "http://www.fastwrite.com/products/focus/Banners/Banner"
szNum = "001"
szExt = ".jpg"
szPath = "O:\SPOT2000"
_screen.picture = IIF( FIL_StringToFile( szPath + szNum + szExt , ;

HTTP_GetURL( szWeb + szNum + szExt ) ;
) , ;
szPath + szNum + szExt,"" )
FIL_tell() : Determines the current location of a file pointer.

Remark
FIL_tell() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_tell() , is set to 2, FIL_tell() will call the _FSeek() FoxPro API
function; if it is set to 1 (Win32 API), FIL_tell() will call the SetFilePointer() Win32 service. A file that has
Syntax
FIL_tell( nHandle )  nCurrentPos

File Functions
Parameters
Returns
nCurrentPos current position of file pointer.
Example
LOCAL nCurrent
LOCAL nEnd
LOCAL nHandle
<...>
nCurrent = FIL_tell( nHandle ) && Save current file pointer
&& position
nEnd = FIL_seek( nHandle,0,2 ) && set file pointer at EOF
FIL_seek( nHandle,nCurrent,0 ) && Reset file pointer to its

&& original position
? "File size :",nEnd && File size !!!
FIL_tree() : Returns a tree of directories.

Syntax
FIL_Tree( szDisk,nBufferLength )  szTree
Parameters
szDisk disk whose directory tree is to be returned.
nBufferLength indicates which space should be reserved to store the resulting string.
Requesting a disk tree is a time consuming process. This function may need dozens of seconds
to complete. Also the returning string may be huge. Therefore, it's the programmer's
responsibility to mention the memory he's keen to reserve for the operation.
Returns
szTree a string in the form of:
"J:\RECYCLED;J:\FAILSAFE.DRV;J:\FAILSAFE.DRV\FAILSAFE;J:\FAILSAFE.DRV\
COMMAND;J:\FAILSAFE.DRV\WINDOWS;J:\FAILSAFE.DRV\DRV;"
Example
? FIL_Tree( "J:",5000 )
FIL_type() : Returns the type of the specified file.

Alias
FileType(), FIL_FileType()
Syntax
FIL_type( szFile )  nType
Parameters
szFile file name.

File Functions
Returns
nType file type
Value Description
0 The type of the specified file is
unknown
1 The specified file is a disk file
2 The specified file is a character file,
typically an LPT device or a console
3 The specified file is either a named or
anonymous pipe
-1 Cannot open the given file
Example
? FIL_type( "LPT1" ) && 2
FIL_unzip() : Decompresses a file.

Caution
The compression format is not compatible with PKzip.
Syntax
FIL_unzip( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn the file to be uncompressed.
szFileOut the resulting file.
Returns
lSuccess .T. indicates that the file was uncompressed successfully; .F. otherwise.
Example
IF ( ! FIL_unzip( "MYFILE.CMP","MYFILE.TXT" ) )
? "An error occurred while uncompressing the file"
ENDIF
See also
FIL_zip().
FIL_where() : Searches for the target file in a set of directories.

Comment
The FIL_where() routine searches for the target file in a set of directories which are listed in an environment
variable. This variable name can be PATH , LIB , INCLUDE , or other user-defined variables.
Syntax
FIL_where( szFile,szEnvironment )  szFullPath

File Functions
Parameters
szFile file to look for.
szEnvironment environment variable. Pay attention to the fact that environment variables are case
sensitive!
Returns
szFullPath full path where szFile was found. If szFile isn’t found in the directory set specified in the
szEnvironment ... environment variable, a null string is returned.
Example
LOCAL szExcel
* If EXCEL is mentionned in the PATH environment variable,

* FIL_where() will find the fullpath where EXCEL.EXE is located
m.szExcel = FIL_where( "EXCEL.EXE","PATH" )
IF ( EMPTY( m.szExcel ) )
&& Consider using FIL_get() rather than GETFILE()
&& in Visual FoxPro
m.szExcel = GETFILE( "EXE","Where is EXCEL.EXE?","Browse",1 )
ENDIF
FIL_wipe() : File wiping.

Comment
The FIL_wipe() routine provides an easy, though not perfect, way to wipe out a file by putting the entire file at
some binary value.
For getting the perfect solution, please head to the homepage of the Wipe utility (http://wipe.sourceforge.net/). Wipe
is a secure file wiping utility. There are some low level issues that must be taken into consideration. One of these is
that there must be some sort of write barrier between passes. Wipe uses fdatasync(2) (or fsync(2) ) as a write
barrier, or if fsync(2) isn't available, the file is opened with the O_DSYNC or O_SYNC flag. For wipe to be effective,
each pass must be completely written. To ensure this, the drive must support some form of a write barrier, write cache
flush, or write cache disabling. SCSI supports ordered command tags, has a force media access bit for commands, and
write cache can be disable on mode page 8. IDE/ATA drives support write cache flushes and write cache disabling.
Unfortunately, not all drives actually disable write cache when asked to. Those drives are broken. Write caching should
always be disabled, unless your system is battery backed and always powers down cleanly.
Syntax
FIL_wipe( szFile )  lSuccess
Parameters
szFile file to wipe out.
Returns
lSuccess .T. if the whole file was written; .F. if not.
Example
&& If you're trying to cheat
IF ( lCheating )
FIL_wipe( "myconfig.dll" )
ENDIF

File Functions
FIL_wreain() : Reads a character string from WIN.INI file.
Syntax
FIL_wreain( szSection,szEntry )  szString
Parameters
szSection section of WIN.INI.
Returns
szString string pertaining to entry.
Example
IF ( FIL_wreain( "MYAPP","PassWord" ) <> cPassWord )
ENDIF
FIL_wriini() : Copies a character string into a .INI file.

Alias
WritePrivateProfileString()
Syntax
FIL_wriini( szSection,szEntry.NULL.,szString.NULL.,szIniFile )  lSuccess
Parameters
szSection section of the .INI file to write to.
szEntry key name that appears under the section name. If this parameter is a .NULL. , the section is
deleted from the .INI file.
szString string to write to .INI file. If this parameter is a .NULL. , the entry is deleted from the .INI
file.
Returns
lSuccess .T. if writing is successful; .F. if not.
Example
IF ( ! FIL_wriini( "WALLPAPER" , ;
"Fill file" , ;
"FILLER.BMP", ;
"MYAPP.INI" ;
) ;
)
? ".INI update failed"
ENDIF

File Functions
FIL_write() : Writes a character string to a file.
Remark
FIL_write() depends on the File Opening Strategy which can be set by the FIL_SetOpenStrategy() function of
Opening Strategy, at the time you call FIL_write() , is set to 2, FIL_write() will call the _FWrite() FoxPro API
function; if it is set to 1 (Win32 API), FIL_write() will call the WriteFile() Win32 service. A file that has been
Syntax
FIL_write( nHandle,szString[,nBytes] )  nWritten
Parameters
szString string to write to the file.
nBytes number of bytes to write. This parameter is optional. When not passed, the entire string is
written to the file.
Returns
nWritten number of bytes actually written to the file
FIL_wsecti() : Reads WIN.INI section.

Syntax
FIL_wsecti( szSection )  cEntries
Parameters
Returns
cEntries all entries for given section.
Example
? "Printer list",FIL_wsecti( "devices" )
FIL_wwriin() : Copies a character string into the WIN.INI file.

Syntax
FIL_wwriin( szSection,szEntry,szString )  lSuccess
Parameters
szString string to write to WIN.INI file.

File Functions
Returns
Example
IF ( ! FIL_wwriin( "MYAPP" , ;
"Desktop" , ;
"640 480 256" ;
) ;
)
ENDIF
FIL_zip() : Compresses a file.

Caution
The compression format is not compatible with PKZip!
Syntax
FIL_zip( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn the file to be compressed.
Returns
lSuccess .T. indicates that the file was compressed successfully; .F. otherwise.
Example
IF ( ! FIL_zip( "MYFILE.TXT","MYFILE.CMP" ) )
? "An error occurred while compressing the file"
ENDIF
See also
FIL_unzip().
FIL_zipLastError() : Last error encountered while in

FIL_zip()/FIL_unzip().
Syntax
FIL_zipLastError()  szLastError
Parameters
None.
Returns
szLastError last error that occurred when using FIL_zip() or FIL_unzip() .

FTP Functions
FTP Functions

FTP Functions
Functions Synopsis
The Internet has changed the way we build applications. Internet technologies and techniques are still in their infancy
but they promise to dramatically affect our applications in general ... NOW. This is not a question of Internet Browsers
but much more deeply a way we will need to interact with resources. This world of connected computers require to get
tools that make it possible to access databases, tables and files anywhere. As such, FOCUS.FLL needed to give the
Visual FoxPro developer the tools to keep in touch with the natural evolution of modern software. That's why we have
made this FTP2 category of functions available to you, the Visual FoxPro Developer.
FTP is another member of the TCP/IP family whose sole purpose was to make it possible to transfer files between
different computer types and different formats. That's why a common protocol such as FTP was born.
Please take also a look at the HTTP/HTML functions of FOCUS.FLL .
FTP functions of FOCUS.FLL are very similar to File functions and you will feel very comfortable with them
FTP Basics
FTP Servers ask for a user login and password. This login information (username + password) is assigned to you by
the Administrator of the FTP Server. Anonymous login is also possible. It provides access to directories of the server to
the public. Anonymous FTP access is performed with .NULL. values in FOCUS.FLL (See the FTP_OpenSession()
function).
Once connected to a FTP site, you need to navigate directories in order to locate the file you want to download. Once
the file has been located, you usually set the transfer mode, either binary or ASCII. With FOCUS.FLL , there is no
need to do this since the binary mode is automatically used as it can be used for ASCII files as well.
The way FOCUS.FLL Works With FTP

Before you can start using FTP functions, you need to open an FTP session to a FTP site. You do this by using the
FTP_OpenSession() function which returns a FOCUS handle to an FTP session. Later on you simply use the handle
of the FTP session to perform FTP operations. When you're done with your FTP connection, you simply close the
session with FTP_CloseSession() .
In between these 2 starting and ending calls , you simply use all the operations you are acquainted with:
 directory creation, renaming, deletion
 file uploads and downloads, deletion, renaming
All FTP functions of FOCUS.FLL are built on the Synchronous model for the sake of convenience. Although more
powerful, asynchronous operations are also much more complex to deal with. Therefore, we have taken the decision to
first introduce synchronous operations ONLY.
FTP Sessions are separate processes. Therefore you cannot use one session with another, even though both sessions
are pointing to the same FTP site. For your convenience, FOCUS.FLL can deal with 10 simultaneous FTP sessions.
A Test FTP Site

FastWrite has created a test FTP site so that you can start testing your functions very easily. This site is available at
the following host: ftp.fastwrite.com . There is one default user that has defined to gain full access to this test
site:
Username: focusfll
Password: ftpfunctions
So ... for example, if you open an FTP session with the following parameters, you should have access to a specific
directory on our server:
nFTPHandle = FTP_OpenSession( "ftp.fastwrite.com","focusfll","ftpfunctions" )
IF ( nFTPHandle >= 0 )
<... more FTP operations here>
FTP_CloseSession( nFTPHandle )
ENDIF
2
File Transfer Protocol

FTP Functions
Some FTP Examples
1. Opening and Closing an FTP session
<... more FTP operations here>
ENDIF
2. Get current directory
? "Current FTP dir:", FTP_GetCurrentDirectory( nFTPHandle )
ENDIF
3. Creating a directory
IF ( ! FTP_CreateDirectory( nFTPHandle,"MyDir" ) )
? "Cannot create directory",FTP_LastError()
ELSE
? "Directory successfully created"
ENDIF
ENDIF
4. Downloading a file from an FTP site
IF ( ! FTP_GetFile( nFTPHandle,"index.htm","c:\myNewIndex.htm" )
? "Cannot retrieve file",FTP_LastError()
ELSE
? "File successfully downloaded"
ENDIF
ENDIF
5. Uploading a file to an FTP site
IF ( ! FTP_PutFile( nFTPHandle,"C:\MYLOCALFILE.TXT","PUBLICFILE.TXT" )
? "Cannot upload file",FTP_LastError()
ELSE
? "File successfully uploaded"
ENDIF
ENDIF

FTP Functions
FTP_CloseAllSessions() : Closes all active FTP sessions.

Syntax
FTP_CloseAllSessions()  lSuccess
Parameters
None.
Returns
lSuccess .T. if all active sessions are closed successfully; .F. otherwise.
Example
LOCAL nFTP1
LOCAL nFTP2
nFTP1 = FTP_OpenSession( "ftp.fastwrite.com","focusfll","ftpfunctions" )

nFTP2 = FTP_OpenSession( "ftp.fastwrite.com","focusfll","ftpfunctions" )
<... more FTP calls>
&& Now I want to close ALL sessions in one shot
IF ( ! FTP_CloseAllSessions() )
? "Some FTP sessions could not be closed"
ENDIF
FTP_CloseSession() : Closes a FTP session for a given site.

Syntax
FTP_CloseSession( nFTPHandle )  lSuccess
Parameters
nFTPHandle FTP session handle.
Returns
lSuccess .T. if the session is successfully closed; .F. otherwise.
Example
FTP_CreateDirectory() : Creates a new directory on the FTP

site.
Alias
FTP_CreateDir(), FTP_MkDir(), FTP_MkDir(), FTP_MakeDir(), FTP_MkDir(),
FTP_MakeDirectory(), FTP_MakeFolder(), FTP_CreateFolder()

FTP Functions
Syntax
FTP_CreateDirectory( nFTPHandle,szDirectory )  lSuccess
Parameters
szDirectory directory to create on the remote system.
Returns
lSuccess .T. if szDirectory was successfully created; .F. otherwise.
FTP_DeleteFile() : Deletes a file stored on the FTP site.

Syntax
FTP_DeleteFile( nFTPHandle,szFile )  lSuccess
Parameters
szFile name of the file to delete on the remote system.
Returns
lSuccess .T. if the file has been successfully deleted; .F. otherwise.
FTP_GetCurrentDirectory() : Retrieves the current directory for

the specified FTP session.
Alias
FTP_GetCurrentDir(), FTP_CurDir(), FTP_CurFolder().
Syntax
FTP_GetCurrentDirectory( nFTPHandle )  szDirectory
Parameters
Returns
szDirectory current directory.

FTP Functions
FTP_GetFile() : Retrieves a file from the FTP site and stores it
locally.
Syntax
FTP_GetFile( nFTPHandle,szSource,szTarget )  lSuccess
Parameters
szSource name of the file to retrieve from the remote system.
szTarget name of the file to create on the local system.
Returns
lSuccess .T. if szSource has successfully retrieved and stored locally; .F. otherwise.
FTP_FindFirstFile() : Searches the specified directory of the

given FTP session.
Syntax
FTP_FindFirstFile( nFTPHandle,szSpec )  szFile
Parameters
szSpec string that specifies a valid directory path or file name for the FTP server's file system. The
string can contain wildcards, but no blank spaces are allowed.
Returns
szFile the name of the first file in the directory of the FTP site or an empty string ( "") if no file can be
found.
Example
szFile = FTP_FindFirstFile( nFTPHandle,"*.*" )

? szFile
szFile = FTP_FindNextFile( nFTPHandle )
ENDDO
FTP_FindNextFile() : Searches for additional files.

Remark
FTP_FindNextFile() has to be preceded by a call to FTP_FindFirstFile() . These functions work very
similarly to the FIL_FindFirst() and FIL_FindNext() of FOCUS.FLL .

FTP Functions
Syntax
FTP_FindNextFile( nFTPHandle )  szFile
Parameters
Returns
szFile the name of the next file in the directory of the FTP site or an empty string ( "") if no file can be
found.
Example
szFile = FTP_FindFirstFile( nFTPHandle,"*.*" )

? szFile
szFile = FTP_FindNextFile( nFTPHandle )
ENDDO
FTP_HandlesCount() : Returns the maximum number of FTP

handles.
Remark
This function can be used instead of making use of hardcoded constants. In the first release of the FTP functions,
FOCUS.FLL has reserved 10 FTP sessions (identified by FTP handles). It may be more in the future so that we have
decided to let a function return this number of sessions.
Syntax
FTP_HandlesCount()  nFTPHandles
Parameters
None.
Returns
nFTPHandles maximum number of FTP handles.
FTP_LastError() : Last error encountered in FTP functions.

Syntax
FTP_LastError()  szLastError
Parameters
None.
Returns
szLastError last error that occurred while using the FTP_*() functions.

FTP Functions
Example
nFTPHandle = FTP_OpenSession( "ftp.fastwrite.com","focusfll","wrongpassword" )
IF ( nFTPHandle >= FTP_MinHandle() .AND. nFTPHandle <= FTP_MaxHandle() )

? "Everything seems to be OK"
ELSE
? "Cannot open FTP session","(" + FTP_LastError() + ")"
*-- Will return something like:
*-- Cannot open FTP session(220 ORION FTP Server (vftpd 1.31) ready.
*-- 331 Password required for focusfll.
*-- 530 Login incorrect.)
ENDIF
FTP_LastVersion() : Returns the file stamp of FTP functions.

Remark
Syntax
FTP_LastVersion()  szLastVersion
Parameters
None.
Returns
"D:\Focus\6.0\ftp.c-Sun Aug 13 15:25:06 2000".
Example
? FTP_LastVersion()
FTP_MaxHandle() : Returns the highest possible FTP handle.

Syntax
FTP_MaxHandle()  nFTPHandle
Parameters
None.
Returns
nFTPHandle highest potential handle.
Example

ENDIF

FTP Functions
FTP_MinHandle() : Returns the lowest possible FTP handle.
Syntax
FTP_MinHandle()  nFTPHandle
Parameters
None.
Returns
nFTPHandle lowest potential handle.
Example

ENDIF
FTP_OpenSession() : Opens an FTP session for a given site.

Syntax
FTP_OpenSession( szFTPSite,szUserName,szPassword )  nFTPHandle
Parameters
szFTPSite FTP session server: a string that forms a valid IP address or a valid host name.
szUserName username. This parameter can be .NULL. for anonymous connections.
szPassword password. This parameter can be .NULL. for anonymous connections.
Returns
nFTPHandle FTP session handle. This number MUST be greater or equal to than FTP_MinHandle() and
less than or equal to FTP_MaxHandle() . Error situations:
Value Description
-1 No FTP handle left
-2 No FTP connection. Use FTP_LastError() to have a more precise idea of
the error type.
-3 No Internet connection. Use FTP_LastError() to have a more precise idea
of the error type.
-4 Invalid szUserName parameter
-5 Invalid szPassword parameter
Example

FTP Functions
FTP_PutFile() : Stores a file on the FTP site.
Syntax
FTP_PutFile( nFTPHandle,szSource,szTarget )  lSuccess
Parameters
szSource name of the file to send from the local system.
szTarget name of the file to create on the remote system.
Returns
lSuccess .T. if the file has been successfully uploaded; .F. otherwise.
FTP_RemoveDirectory() : Removes the specified directory on

the FTP site.
Alias
FTP_RemoveDir(), FTP_DeleteDir(), FTP_DeleteDirectory(), FTP_DeleteFolder(),
FTP_RemoveFolder()
Syntax
FTP_RemoveDirectory( nFTPHandle,szDir )  lSuccess
Parameters
szDir name of the directory to delete on the remote system.
Returns
lSuccess .T. if the directory has been successfully removed; .F. otherwise.
FTP_RenameFile() : Renames a file or directory stored on the

FTP site.
Alias
FTP_RenameDir(), FTP_RenameDirectory(), FTP_RenameFolder()
Syntax
FTP_RenameFile( nFTPHandle,szSource,szTarget )  lSuccess
Parameters
szSource name of the file that will have its name changed on the remote FTP site.

FTP Functions
szTarget new name for the remote file.
Returns
lSuccess .T. if the file has been successfully renamed; .F. otherwise.
FTP_SetCurrentDirectory() : Changes to a different working

directory on the FTP site.
Alias
FTP_SetCurrentDirectory(), FTP_ SetCurrentDir(), FTP_ SetCurrentFolder(), FTP_ChDir(),
FTP_cd()
Syntax
FTP_SetCurrentDirectory( nFTPHandle,szDir )  lSuccess
Parameters
szDir name of the directory to change to on the remote system. This can be either a fully qualified
path or a name relative to the current directory.
Returns

Graphical Functions
Graphical/GDI Functions

Graphical Functions
Functions Synopsis
FOCUS.FLL provides some useful GDI functions (Graphic Device Interface) which are not provided by Visual FoxPro,
even though accessible via the Win32 API. A companion OCX also exists: FOCUSGDI that is distributed separately.
In particular, FOCUS.FLL makes it possible to create outstanding splash screens thanks to the Region functions. In
the following documentation, the user will find real examples that we did program for our own needs.

Graphical Functions
GDI_CreateEllipticRegion() : Creates an elliptical region.

Syntax
GDI_CreateEllipticRegion( nTop,nLeft,nBottom,nRight )  hRegion
Parameters
nTop specifies the logical y-coordinate of the upper-left corner of the bounding rectangle.
nLeft specifies the logical x-coordinate of the upper-left corner of the bounding rectangle.
nBottom specifies the logical y-coordinate of the lower-right corner of the bounding rectangle.
nRight specifies the logical x-coordinate of the lower-right corner of the bounding rectangle.
Please notice that for the region to take effect, you must attach it to the form with
GDI_SetWindowRegion() .
Please remember to use ALWAYS the GDI_DeleteRegion() function when you no

longer need the region.
Returns
hRegion the handle to a GDI region if the function is successful; 0 if the function failed.
Example
LOCAL nTop, nLeft, nBottom, nRight
&& INIT event of the form ===============================================================

WITH ThisForm
&& Of course ... load FOCUS.FLL, please

IF ( ! "FOCUS.FLL" $ SET( "LIBRARY" ) )
ENDIF
&& Obtain the window handle and assign it to a property that we have defined
.hWnd = WIN_hwnd( This.caption )
&& The width of the form is EXACTLY the width of the image
.Width = .imgBackground.Width
&& The height of the form is EXACTLY the height of the image
.Height = .imgBackground.Height
DODEFAULT()
m.nTop = 0 && The ellipse will be created at the topmost position

m.nLeft = 0 && The ellipse will be created at the leftmost position
m.nBottom = .Height && The bottom of the ellipse is equal to the height of the form
m.nRight = .Width && The width of the ellipse is equal to the width of the form
&& We have created a property called "hRegion"; this property is

&& assigned with the return of GDI_CreateEllipticRegion()
.hRegion = GDI_CreateEllipticRegion( m.nTop , ;
m.nLeft , ;
m.nBottom , ;
m.nRight )
&& If the region that was given is a valid region

IF ( .hRegion != 0 )
&& Attach the region to the form
GDI_SetWindowRegion( .hWnd,.hRegion,"ELLIPSE" )
ENDIF
ENDWITH

Graphical Functions
&& DESTROY event of the form ============================================================
IF ( ThisForm.hRegion != 0 )
&& Even if we don't need to do this (because the form will be deleted anyway)
&& it's a good idea to do it ALWAYS:
&& 1) Detach the region
GDI_DetachWindowRegion( ThisForm.hWnd,"ELLIPSE" )
&& 2) Free some GDI objects that were still holding the region in memory
GDI_DeleteRegion( ThisForm.hRegion )
ENDIF
CLEAR EVENTS
The example of above creates the an elliptical form. The elliptical form is created thanks to a to the
GDI_CreateEllipticRegion() function; then the region is attached to the form ( GDI_SetWindowRegion() ).
To beautify the presentation of the form, we have created a JPG file that fills perfectly the ellipse.
GDI_CreatePolygonalRegion() : Creates a region based on a

polygon.
Remark
The EXACT construction of a polygon can take some time to fine-tune, especially if you want to decorate the polygon
with an outstanding image. When we need to achieve this, we first build the image, and we display it in a form. Then
we set the mousemove() event of the form to display the current coordinates of the mouse. We gently spot the
locations where we need to place the points of our polygon and we note these coordinates. Afterward, we create the
array with the points that were noted. This is the easiest way to create amazing splash screens.
Syntax
GDI_CreatePolygonalRegion( @aPoints,nMode )  hRegion
Parameters
aPoints an array of x,y coordinates.
nMode specifies the filling mode of the polygon: 1 for alternate; 2 for winding.

Returns
Example
LOCAL hRegion1
LOCAL hRegion2
LOCAL nTop
LOCAL nLeft
LOCAL nBottom
Graphical Functions
LOCAL nRight
LOCAL ARRAY aPoints[7,2]
#define RGN_AND 1
#define RGN_OR 2
#define RGN_XOR 3
#define RGN_DIFF 4
#define RGN_COPY 5
WITH ThisForm
&& Please load FOCUS.FLL

ENDIF
DODEFAULT()
m.nTop = 0
m.nLeft = 0
m.nBottom = .Top + .Height
m.nRight = .Left + .Width
aPoints[1,1] = 81 && x1
aPoints[1,2] = 115 && y1
aPoints[2,1] = 132 && x2
aPoints[2,2] = 85 && y2
aPoints[3,1] = 151 && x3
aPoints[3,2] = 0 && y3
aPoints[4,1] = 194 && x4
aPoints[4,2] = 16 && y4
aPoints[5,1] = 237 && x5
aPoints[5,2] = 0 && y5
aPoints[6,1] = 255 && x6
aPoints[6,2] = 85 && y6
aPoints[7,1] = 310 && x7
aPoints[7,2] = 115 && y7
m.hRegion1 = GDI_CreatePolygonalRegion( @aPoints,1 )
aPoints[1,1] = 76 && x1
aPoints[1,2] = 145 && y1
aPoints[2,1] = 196 && x2
aPoints[2,2] = 186 && y2
aPoints[3,1] = 312 && x3
aPoints[3,2] = 145 && y3
aPoints[4,1] = 253 && x4
aPoints[4,2] = 254 && y4
aPoints[5,1] = 134 && x5
aPoints[5,2] = 254 && y5
.hRegion = GDI_CombineRegions( m.hRegion1,m.hRegion2,RGN_OR )
&& If the combination of regions is OK

&& Free all the internal objects that were declared

&& with the previous calls
GDI_DeleteRegion( m.hRegion1 )
&& Create a new region

m.hRegion2 = GDI_CreateEllipticRegion( 225,0,475,387 )
&& And combine this regions with the region we already have
.hRegion = GDI_CombineRegions( .hRegion,m.hRegion2,RGN_OR )

Graphical Functions
&& Free all the internal objects that were declared
&& with the previous call

aPoints[1,1] = 160
aPoints[1,2] = 170
aPoints[2,1] = 174
aPoints[2,2] = 170
aPoints[3,1] = 146
aPoints[3,2] = 208
aPoints[4,1] = 135
aPoints[4,2] = 201
&& And create a new polygonal region

&& If the creation of the region was successful

IF ( m.hRegion2 != 0 )
&& Combine this new region with what was constucted up to now
.hRegion = GDI_CombineRegions( .hRegion,m.hRegion2,RGN_XOR )
&& If we could combine the regions together

&& Attach the final region to the form
GDI_SetWindowRegion( .hWnd,.hRegion,"SPY" )
ENDIF
&& And … once again, free all intrenal objects

ENDIF
ENDIF
ENDIF
ENDWITH

GDI_DetachWindowRegion( ThisForm.hWnd,"SPY" )
ENDIF
CLEAR EVENTS
The example of above creates a form that is based on several regions. To beautify the presentation of the form, we
have created a JPG file that fills perfectly the combination of regions: our own spy, with a green background! We have
moved this image over some C code of FOCUS.FLL so that you can see that the form has some transparent regions.

Graphical Functions
GDI_DeleteRegion() : Frees a region and all its associated

internal GDI objects.
Syntax
GDI_DeleteRegion( hRegion )  lSuccess
Parameters
hRegion handle to a GDI region. This handle is typically given by a previous call to
GDI_CreateRectangleRegion() , GDI_CreateEllipticRegion() , etc.
Returns
lSuccess .T. if the function was successful; .F. if not.
Example

WITH ThisForm
&& Of course ... load FOCUS.FLL, please

ENDIF
&& Obtain the window handle and assign it to a property that we have defined
&& The width of the form is EXACTLY the width of the image
&& The height of the form is EXACTLY the height of the image
DODEFAULT()
m.nTop = 0 && The ellipse will be created at the topmost position

m.nLeft = 0 && The ellipse will be created at the leftmost position

Graphical Functions
m.nBottom = .Height && The bottom of the ellipse is equal to the height of the form
m.nRight = .Width && The width of the ellipse is equal to the width of the form
&& We have created a property called "hRegion"; this property is

&& assigned with the return of GDI_CreateEllipticRegion()
.hRegion = GDI_CreateEllipticRegion( m.nTop , ;
m.nLeft , ;
m.nBottom , ;
m.nRight )
&& If the region that was given is a valid region

&& Attach the region to the form
GDI_SetWindowRegion( .hWnd,.hRegion,"ELLIPSE" )
ENDIF
ENDWITH

GDI_DetachWindowRegion( ThisForm.hWnd,"ELLIPSE" )
ENDIF
CLEAR EVENTS
GDI_CombineRegions() : Creates a rectangular region.

Syntax
GDI_CreateRectangleRegion( hRegion1,hRegion2,nMode )  hRegion
Parameters
hRegion1 the handle to the first GDI region if the function is successful.
hRegion2 the handle to the second GDI region if the function is successful.
nMode combination mode. The following modes can be used:
RGN_AND 1
RGN_OR 2
RGN_XOR 3
RGN_DIFF 4
RGN_COPY 5

Graphical Functions
Returns
Example
LOCAL hRegion1, hRegion2
LOCAL nRandom
#define RGN_AND 1
#define RGN_OR 2
#define RGN_XOR 3
#define RGN_DIFF 4
#define RGN_COPY 5
WITH ThisForm
&& Please use FOCUS.FLL

ENDIF
&& Get the window handle

.Width = 150
.Height = 150
DODEFAULT()
m.nTop = 0
m.nLeft = 0
m.nBottom = 100
m.nRight = 100
&& Generate a random number with a specific seed

m.nRandom = RAND( SYS_GetTickCount() / SECONDS() * TIM_time() )
&& If upper half of the random range

IF ( m.nRandom > 0.5 )
&& Create TWO rectangular regions, and combine them later
m.hRegion1 = GDI_CreateRectangleRegion( m.nTop , ;
m.nLeft , ;
m.nBottom, ;
m.nRight )
m.hRegion2 = GDI_CreateRectangleRegion( m.nTop + 50, ;

m.nLeft + 50, ;
m.nBottom + 50, ;
m.nRight + 50 )
&& Use a specific JPG file to fill the TWO rectangular regions
.imgBackground.picture = "multiregions.jpg"
ELSE
&& If lower half of the random range
&& Create TWO circles, and combine them together later
m.hRegion1 = GDI_CreateEllipticRegion( m.nTop , ;
m.nLeft , ;
m.nBottom, ;
m.nRight )
m.hRegion2 = GDI_CreateEllipticRegion( m.nTop + 50, ;

m.nLeft + 50, ;
m.nBottom + 50, ;
m.nRight + 50 )
&& Use a specific JPG file to fill the TWO circles

.imgBackground.picture = "multiregions02.jpg"
ENDIF
&& Combine the regions together to form a very beautiful form

&& If the combination of regions did succeed


Graphical Functions
&& Attach the region to the current form
GDI_SetWindowRegion( .hWnd,.hRegion,"DOUBLE_SHAPE" )
ENDIF
ENDWITH

GDI_DetachWindowRegion( ThisForm.hWnd,"DOUBLE_SHAPE" )
ENDIF
CLEAR EVENTS
The example of above creates a form with irregular shape: either two circles combined together or two rectangles
combined together.
To beautify the presentation of the form, we have created two JPG files that fill perfectly the combination of regions.
GDI_CreateRectangleRegion() : Creates a rectangular region.

Syntax
GDI_CreateRectangleRegion( nTop,nLeft,nBottom,nRight )  hRegion
Parameters
nTop specifies the logical y-coordinate of the upper-left corner of the rectangle.
nLeft specifies the logical x-coordinate of the upper-left corner of the rectangle.
nBottom specifies the logical y-coordinate of the lower-right corner of the rectangle.
nRight specifies the logical x-coordinate of the lower-right corner of the rectangle.

Returns
Example
LOCAL hRegion1, hRegion2
LOCAL nRandom
#define RGN_AND 1
#define RGN_OR 2
#define RGN_XOR 3
#define RGN_DIFF 4

Graphical Functions
#define RGN_COPY 5
WITH ThisForm
&& Please use FOCUS.FLL

ENDIF
&& Get the window handle

.Width = 150
.Height = 150
DODEFAULT()
m.nTop = 0
m.nLeft = 0
m.nBottom = 100
m.nRight = 100
&& Generate a random number with a specific seed

m.nRandom = RAND( SYS_GetTickCount() / SECONDS() * TIM_time() )
&& If upper half of the random range

IF ( m.nRandom > 0.5 )
&& Create TWO rectangular regions, and combine them later
m.hRegion1 = GDI_CreateRectangleRegion( m.nTop , ;
m.nLeft , ;
m.nBottom, ;
m.nRight )
m.hRegion2 = GDI_CreateRectangleRegion( m.nTop + 50, ;

m.nLeft + 50, ;
m.nBottom + 50, ;
m.nRight + 50 )
&& Use a specific JPG file to fill the TWO rectangular regions
.imgBackground.picture = "multiregions.jpg"
ELSE
&& If lower half of the random range
&& Create TWO circles, and combine them together later
m.hRegion1 = GDI_CreateEllipticRegion( m.nTop , ;
m.nLeft , ;
m.nBottom, ;
m.nRight )
m.hRegion2 = GDI_CreateEllipticRegion( m.nTop + 50, ;

m.nLeft + 50, ;
m.nBottom + 50, ;
m.nRight + 50 )
&& Use a specific JPG file to fill the TWO circles

.imgBackground.picture = "multiregions02.jpg"
ENDIF
&& Combine the regions together to form a very beautiful form

&& If the combination of regions did succeed

&& Attach the region to the current form
GDI_SetWindowRegion( .hWnd,.hRegion,"DOUBLE_SHAPE" )
ENDIF
ENDWITH

GDI_DetachWindowRegion( ThisForm.hWnd,"DOUBLE_SHAPE" )

Graphical Functions
ENDIF
CLEAR EVENTS
The example of above creates a form with irregular shape: either two circles combined together or two rectangles
combined together.
To beautify the presentation of the form, we have created two JPG files that fill perfectly the combination of regions.
GDI_Ellipse() : Draws an ellipse.

Syntax
GDI_Ellipse( nHDC,nTop,nLeft,nBottom,nRight,nWidth,nHeight )  lSuccess
Parameters
nHDC handle to device context.
Returns
Example
LOCAL hWnd
LOCAL hDC
LOCAL nTop
LOCAL nLeft
LOCAL nBottom
LOCAL nRight
LOCAL nWidth
LOCAL nHeight
LOCAL nWidth2
LOCAL nHeight2
m.hWnd = WIN_hwnd( ThisForm.caption )

m.hDC = WIN_GetWindowDC( m.hWnd )
m.nLeft = 150
m.nTop = 100
m.nRight = 400
m.nBottom = 125
m.nWidth = 30
m.nHeight = 30
m.nWidth2 = 55
m.nHeight2 = 55
GDI_RoundRectangle( hDC , ;
m.nTop , ;
m.nLeft , ;
m.nBottom , ;
m.nRight , ;
m.nWidth , ;

Graphical Functions
m.nHeight )
GDI_Rectangle( hDC , ;
m.nBottom+5 , ;
m.nLeft , ;
m.nBottom+5+25, ;
m.nRight )
GDI_Ellipse( hDC , ;
m.nTop , ;
m.nLeft-60 , ;
m.nTop+m.nHeight2, ;
m.nLeft-60+m.nWidth2 )
WIN_ReleaseDC( m.hWnd,m.hDC )
The example of above creates the following output. Please notice that GDI function calls might need to be re-
created in the paint() event of your forms to have a persistent effect.
GDI_LastVersion() : Returns the file stamp of GDI functions.

GRA_LastVersion() : Returns the file stamp of GRA
functions.
Remark
Syntax
GDI_LastVersion()  szLastVersion
GRA_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\GRAPHIC.C-Mon Oct 19 15:55:22 1998" .

Graphical Functions
GDI_Rectangle() : Draws a rectangle.
Syntax
GDI_Rectangle( nHDC,nTop,nLeft,nBottom,nRight,nWidth,nHeight )  lSuccess
Parameters
nWidth specifies the width of ellipse.
nHeight specifies the height of ellipse.
Returns
Example
LOCAL hWnd
LOCAL hDC
LOCAL nTop
LOCAL nLeft
LOCAL nBottom
LOCAL nRight
LOCAL nWidth
LOCAL nHeight
LOCAL nWidth2
LOCAL nHeight2

m.nLeft = 150
m.nTop = 100
m.nRight = 400
m.nBottom = 125
m.nWidth = 30
m.nHeight = 30
m.nWidth2 = 55
m.nHeight2 = 55
m.nTop , ;
m.nLeft , ;
m.nBottom , ;
m.nRight , ;
m.nWidth , ;
m.nHeight )
m.nBottom+5 , ;
m.nLeft , ;
m.nBottom+5+25, ;
m.nRight )
m.nTop , ;
m.nLeft-60 , ;

Graphical Functions
GDI_RoundRectangle() : Draws a round rectangle.

Syntax
GDI_RoundRectangle( nHDC,nTop,nLeft,nBottom,nRight,nWidth,nHeight )  lSuccess
Parameters
nWidth specifies the width of ellipse.
nHeight specifies the height of ellipse.
Returns
lSuccess .T. if the round rectangle was drawn; .F. if not.
Example
LOCAL hWnd
LOCAL hDC
LOCAL nTop
LOCAL nLeft
LOCAL nBottom
LOCAL nRight
LOCAL nWidth
LOCAL nHeight
LOCAL nWidth2
LOCAL nHeight2

m.nLeft = 150
m.nTop = 100
m.nRight = 400
m.nBottom = 125
m.nWidth = 30
m.nHeight = 30
m.nWidth2 = 55
m.nHeight2 = 55
m.nTop , ;

Graphical Functions
m.nLeft , ;
m.nBottom , ;
m.nRight , ;
m.nWidth , ;
m.nHeight )
m.nBottom+5 , ;
m.nLeft , ;
m.nBottom+5+25, ;
m.nRight )
m.nTop , ;
m.nLeft-60 , ;
GDI_ScreenToClient() : Converts the screen coordinates of a

specified point on the screen to client-area coordinates.
Syntax
GDI_ScreenToClient( hWnd,@x,@y )  .T.
Parameters
hWnd Handle to the window whose client area will be used for the conversion.
x X of the screen coordinates to be converted. Must be passed by reference.
y X of the screen coordinates to be converted. Must be passed by reference.
Returns
.T. the function always returns .T.

Graphical Functions
GDI_ClientToScreen () : Converts the client-area coordinates of
a specified point to screen coordinates.
Syntax
GDI_ClientToScreen( hWnd,@x,@y )  .T.
Parameters
hWnd Handle to the window whose client area will be used for the conversion.
x X of the client coordinates to be converted. Must be passed by reference.
y Y of the client coordinates to be converted. Must be passed by reference.
Returns
ALL THE GDI FUNCTIONS THAT FOLLOW ARE STILL UNDER DEVELOPMENT AND TESTING. WE DO
RECOMMEND NOT USING THEM YET BECAUSE THEIR USAGE CAN STILL CHANGE, ESPECIALLY THE ORDER
OF THE PARAMETERS!
GDI_Arc() : Draws an elliptical arc.

Remark
The Arc() method is similar to ArcTo() except that the cursor position is not updated.
Syntax
GDI_Arc( nHDC,nLeft,nTop,nRight,nBottom,nXStart,nYStart,nXEnd,nYEnd ) -> lSuccess
Parameters
Windows 95/98: The sum of nLeft plus nRight must be less than 32768 .
Windows 95/98: The sum of nTop plus nBottom must be less than 32768 .
nRight Specifies the logical x-coordinate of the lower-right corner of the bounding rectangle.
Windows 95/98: The sum of nLeft plus nRight must be less than 32768 .
Windows 95/98: The sum of nTop plus nBottom must be less than 32768 .
nXStart specifies the logical x-coordinate of the ending point of the radial line defining the starting point
of the arc.
nYStart specifies the logical y-coordinate of the ending point of the radial line defining the starting point
of the arc.
nXEnd specifies the logical x-coordinate of the ending point of the radial line defining the ending point
of the arc.
nYEnd specifies the logical y-coordinate of the ending point of the radial line defining the ending point
of the arc.
Returns
lSuccess the function returns an object handle. The cursor position is not updated.

Graphical Functions
GDI_ArcTo() : Draws an elliptical arc.
Remark
The ArcTo() method is similar to Arc() except that the cursor position is updated.
Syntax
ArcTo( nHDC,nLeft,nTop,nRight,nBottom,nXStart,nYStart,nXEnd,nYEnd ) -> nObject
Parameters
nLeft specifies the logical x-coordinate of the upper-left corner of the bounding rectangle. Windows
95/98: The sum of nLeft plus nRight must be less than 32768 .
nTop specifies the logical y-coordinate of the upper-left corner of the bounding rectangle. Windows
95/98: The sum of nTop plus nBottom must be less than 32768 .
nRight specifies the logical x-coordinate of the lower-right corner of the bounding rectangle. Windows
95/98: The sum of nLeft plus nRight must be less than 32768 .
nBottom specifies the logical y-coordinate of the lower-right corner of the bounding rectangle. Windows
95/98: The sum of nTop plus nBottom must be less than 32768 .
nXStart specifies the logical x-coordinate of the ending point of the radial line defining the starting point
of the arc.
nYStart specifies the logical y-coordinate of the ending point of the radial line defining the starting point
of the arc.
nXEnd specifies the logical x-coordinate of the ending point of the radial line defining the ending point
of the arc.
nYEnd specifies the logical y-coordinate of the ending point of the radial line defining the ending point
of the arc.
Returns
nObject the function returns an object handle.
GDI_CreateSolidBrush() : Creates a brush that has the

specified hatch pattern and color.
Syntax
GDI_CreateSolidBrush( nStyle,nRed,nGreen,nBlue ) -> nObject
Parameters
nStyle specifies the hatch style of the brush. This parameter can be one of the following values:
Value Description
0 Solid
1 Diagonal
2 Cross
3 Diagonal cross
4 Diagonal
5 Horizontal
6 Vertical
nRed specifies the intensity of the red color.
nGreen specifies the intensity of the green color.
nBlue specifies the intensity of the blue color.

Graphical Functions
Returns
GDI_chord() : Draws a chord.

Remark
A chord is a region bounded by the intersection of an ellipse and a line segment, called a secant. The chord is outlined
by using the current pen and filled by using the current brush.
The curve of the chord is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point
where the ellipse intersects the first radial and extends counterclockwise to the point where the ellipse intersects the
second radial. The chord is closed by drawing a line from the intersection of the first radial and the curve to the
intersection of the second radial and the curve.
If the starting point and ending point of the curve are the same, a complete ellipse is drawn.
The current position is neither used nor updated by Chord() .
Syntax
GDI_Chord( nHDC,nLeft,nTop,nRight,nBottom,nXStart,nYStart,nXEnd,nYEnd ) -> nObject
Parameters
nXStart specifies the x-coordinate of the endpoint of the radial defining the beginning of the chord.
nYStart specifies the y-coordinate of the endpoint of the radial defining the beginning of the chord.
nXEnd specifies the x-coordinate of the endpoint of the radial defining the end of the chord.
nYEnd specifies the y-coordinate of the endpoint of the radial defining the end of the chord.
Returns
GDI_circle() : Draws a circle

Comment
We still experiment problems with Visual FoxPro with GRA_*() functions. We have to fine-tune this.
Syntax
GDI_circle( n1,n2,n3,n4 )  .T.
Parameters
n1 ???
n2 ???
n3 ???
n4 ???
Returns

Graphical Functions
GRA_line() : Draws a line.
Comment
We still experiment problems with Visual FoxPro with GRA_*() functions. We have to fine tune this.
Syntax
GRA_line( n1,n2,n3,n4,n5,n6,n7,n8,n9 )  .T.
Parameters
n1 ???
n2 ???
n3 ???
n4 ???
n5 ???
n6 ???
n7 ???
n8 ???
n9 ???
Returns
GDI_SetPixel() : Draws a pixel.

Syntax
GDI_SetPixel( nHDC,nX,nY,nRed,nGreen,nBlue )  lSuccess
Parameters
nX X-coordinate of pixel.
nY Y-coordinate of pixel
nRed red component of RGB color.
nGreen green component of RGB color.
nBlue blue component of RGB color.
Returns
lSuccess .T. if the pixel was drawn; .F. if not.
GRA_carve() : Draws a box with carving effect.

Special
We still experiment problems with Visual FoxPro with GRA_*() functions. We have to fine-tune this.
Syntax
GRA_carve( nTop,nLeft,nBottom,nRight )  nCode
Parameters
nTop top of rectangle

Graphical Functions
nLeft left of rectangle
nBottom bottom of rectangle
nRight right of rectangle
Returns
nCode 0 if function is successful
-1 if function failed creating a device context
-2 if function failed creating a pen
-3 if function failed drawing a line
-4 if function failed moving to the origin of the drawing region
-5 if function failed selecting the appropriate objects

HTML/HTTP Functions
HTML/HTTP Functions

HTML/HTTP Functions
Functions Synopsis
The Internet has changed the way we build applications. Internet technologies and techniques are still in their infancy
but they promised to dramatically affect our applications in general. This is not a question of Internet Browsers but
much more deeply a way we will need to interact with resources. This world of connected computers require to get
tools that make it possible to access databases, tables and files anywhere. As such, FOCUS.FLL needed to give the
Visual FoxPro developer the tools to keep in touch with the natural evolution of modern software.
With version 7.85 of FOCUS.FLL we have built our very first Internet functions. Many of the internals of FOCUS.FLL
will change in the future while preserving your existing code. More will come as time goes by.
Please take also a look at the FTP functions of FOCUS.FLL .

HTML/HTTP Functions
HTML_Decode() : decodes an HTML encoded string.

Caution
The internal buffer used by the HTML_Decode() function cannot contain more than 4096 characters.
Syntax
HTTP_Decode( szHtml] )  szString
Parameters
szHTML the resulting encoded string.
Returns
szString the string to HTML encode.
Example
? HTML_Decode(HTML_Encode( ["Ce bel été"] )) && "Ce bel été"
HTML_Encode() : applies HTML encoding to the specified text

string.
Remark
The HTML_Encode() applies HTML encoding to the specified text string. Its typical use is to display the contents of
text fields contained in a database in HTML. Characters in the string such as “<” and “&” that have special meanings
in HTML are converted into their HTML equivalents, such as < and & so that they will be displayed correctly
by the client browser.
If the text string to be displayed already contains HTML encoding, do not use the HTML_Encode() function. For
example, suppose a product description field contains HTML-encoded text such as "The Classic Diner
Clock brings the age of the "Golden Oldies" to your kitchen." . This string
uses the tag to format italic text and the " sequence to display quotation marks when displayed by the
client browser. Because the string is already coded in HTML, you do not need to encode it again. Double-encoding
the string would produce incorrect results.
From To From To
"&" "&" "Ò" "&Ograv;"
"<" "<" "Ó" "Ó"
">" ">" "Ô" "Ô"
""" """ "Õ" "Õ"
"°" "°" "à" "à"
"²" "²" "á" "á"
"³" "³" "â" "â"
"¶" "¶" "ã" "ã"
"±" "±" "Ö" "ö"
"©" "©" "÷" "÷"
"«" "«" "ù" "ù"
"®" "®" "ú" "ú"
"»" "»" "û" "û"
"¼" "¼" "ü" "ü"
"½" "½" "æ" "æ"
"¾" "¾" "é" "é"
"À" "À" "ê" "ê"
"Á" "Á" "ë" "ë"

HTML/HTTP Functions
"Â" "Â" "Ì" "ì"
"Ã" "&Atild;" "Í" "í"
"Ä" "Ä" "Ò" "ò"
"Å" "Å" "Ó" "ó"
"Æ" "Æ" "Ô" "ô"
"È" "&Egrav;" "Õ" "õ"
"É" "É" "é" "é"
"Ê" "Ê" "è" "è"
"\n" " "
(CHR(13)+CHR(10))
Caution
The internal buffer used by the HTML_Encode() function cannot contain more than 4096 characters.
Syntax
HTTP_Encode( szString] )  szHTML
Parameters
szString the string to HTML encode.
Returns
szHTML the resulting encoded string.
Example
? HTML_Encode( ["Ce bel été"] ) && "Ce bel été"
HTML_LastVersion() : Returns the file stamp of HTML

functions.
Remark
Syntax
HTML_LastVersion()  szLastVersion
Parameters
None.
Returns
HTTP_AttemptConnect() : Attempts to make a connection to

the Internet.
Remark
This function allows an application to first attempt to connect before issuing any requests. A client program can use
this to evoke the dial-up dialog box. If the attempt fails, the application should enter offline mode.

HTML/HTTP Functions
Syntax
HTTP_AttemptConnect()  lSuccess
Parameters
None.
Returns
lSuccess .T. if the connection has been made; .F. if not.
Example
IF ( ! HTTP_AttemptConnect() )
IF ( HTTP_InternetDial( "MyDialUp" ) )
? "You're connected to the Internet"
ENDIF
ENDIF
HTTP_CanonicalizeURL() : Canonicalizes a URL, which

includes converting unsafe characters and spaces into
escape sequences.
Remark
A Uniform Resource Locator (URL) is a compact representation of the location and access method for a resource
located on the Internet. Each URL consists of a scheme (HTTP, HTTPS, FTP, or Gopher) and a scheme-specific string.
This string can also include a combination of a directory path, search string, or name of the resource. The FOCUS
Internet functions provide the ability to split and canonicalize URLs.
The format of all URLs must follow the accepted syntax and semantics in order to access resources through the
Internet. Canonicalization is the process of formatting a URL to follow this accepted syntax and semantics.
Characters that must be encoded include any characters that have no corresponding graphic character in the US-ASCII
coded character set (hexadecimal 80-FF, which are not used in the US-ASCII coded character set, and hexadecimal
00-1F and 7F, which are control characters), blank spaces, "%" (which is used to encode other characters), and unsafe
characters (<, >, ", #, {, }, |, \, ^, ~, [, ], and ').
If HTTP_CanonicalizeURL() is used on the canonicalized URL, the escape sequence "%25" would be converted
into the escape sequence "%2525" , which would not work properly.
Do not use the HTTP_CanonicalizeURL() to encode HTML text: use the HTML_Encode() function instead.
Syntax
HTTP_CanonicalizeURL( szURL] )  szComponent
Parameters
szURL the URL to canonicalize.
Returns
szComponent the resulting canonicalized URL.
Example
? HTTP_canonicalizeURL( "http://www.fastwrite.com/does not exist/index.htm" )
&& http://www.fastwrite.com/does%20not%20exist/index.htm
See Also
HTTP_URLEncode() ,HTTP_URLDecode() .

HTML/HTTP Functions
HTTP_CrackURL() : Cracks a URL into a domain and path.
Syntax
HTTP_CrackURL( szURL[,nType] )  szComponent
Parameters
szURL the base URL to access.
nType optional parameter.
Value Description
0 Host name (domain)
1 Path
2 Host name (domain) + Path
Returns
szComponent the desired component.
Example
LOCAL szDomain
LOCAL szPath
LOCAL szStatus
#define HTTP_QUERY_STATUS_CODE 19
&& Let's split the URL into a domain name and a path
&& For example, http://www.fastwrite.com/images/BannerVFP.jpg is the complete URL
&& szDomain = HTTP_CrackURL( szFull,0 ) -> "www.fastwrite.com"

&& szPath = HTTP_CrackURL( szFull,1 ) -> "/images/BannerVFP.jpg"
szDomain = HTTP_CrackURL( szURL,0 ) && Get the host name

szPath = HTTP_CrackURL( szURL,1 ) && Get the path
&& Now ... let's ask FOCUS.FLL whether that resource exist
szStatus = HTTP_IsURL( szDomain,szPath,HTTP_QUERY_STATUS_CODE )
&& "200" means OK; 404 means page not found; 403 means Forbidden ... these codes
&& are the same as the ones used in Internet Explorer
IF ( szStatus != "200" )
? "Resource exists!"
ENDIF
HTTP_CombineURL() : Combines a base and a relative URL

into a single URL.
Syntax
HTTP_CombineURL( szBaseURL,szRelURL )  szURL
Parameters
szBaseURL the base URL to access.
szRelURL the relative URL.
Returns
szURL the combined URL.

HTML/HTTP Functions
Example
&& In this example, you see that meta sequences such as "." and ".." are removed
&& from the final URL
? HTTP_CombineURL( "http://www.fastwrite.com","products/./../products/focus/vcx" )
&& "http://www.fastwrite.com/products/focus/vcx"
&& In this example you see that the space is converted to a %XX sequence
? HTTP_CombineURL( "http://www.fastwrite.com","focus /vcx" )
&& http://www.fastwrite.com/focus%20/vcx
HTTP_DecodeQueryString() : Decodes the QUERY_STRING of

a URL request.
Syntax
HTTP_DecodeQueryString( szQueryString )  szDecodedString
Parameters
szQueryString the query string to decode.
Returns
szDecodedString the decoded query string, or an empty string if an error occurred.
You can use the DD to decode query string sent to a web application server. If for example you request a URL with
some parameters, this function will be very handy:
"http://www.fastwrite.com/products/dynafox/01.fxp?Name=Pat%20Boens&action=Change%20password" can
be turned to "Name=Pat Boens&action=Change password" .
HTTP_GetCodeText() : Returns a descriptive text

corresponding to a given HTTP responde code.
Syntax
HTTP_GetCodeText( m.szCode )  szDesc
Parameters
szCode code to obtain a descriptive text for.
100 Continue
101 Switching Protocols
200 OK
201 Created
202 Accepted
203 Non-Authoritative Information
204 No Content
205 Reset Content
206 Partial Content
300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
307 Temporary Redirect
400 Bad Request
401 Unauthorized
402 Payment Required

HTML/HTTP Functions
403 Forbidden
404 Not Found
405 Method not allowed
406 Not acceptable
407 Proxy Authentication Required
408 Request Time-Out
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Request Entity Too Large
414 Request URI Too Large
415 Unsupported Media Type
416 Requested range not satisfiable
417 Expectation Failed
500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Time-Out
505 HTTP Version Not Supported
Returns
szDesc description.
Example
? HTTP_GetCodeText( "500" ) && "Internal Server Error"
? HTTP_GetCodeText( "200" ) && "OK"
? HTTP_GetCodeText( "404" ) && "Not Found"
HTTP_GetDefaultBrowser() : Returns the default browser

application that will be invoked for *.htm files.
Syntax
HTTP_GetDefaultBrowser()  szBrowser
Parameters
None
Returns
szBrowser full path to browser application or empty string ("") in case of error.
Example
LOCAL nChoice
LOCAL szBrowser
LOCAL szURL
LOCAL szCmd
LOCAL oIE
LOCAL szClass
#define CH_GO_WEB 1
m.szClass = "INTERNETEXPLORER.APPLICATION" && Class to use

m.szURL = ALLTRIM( This.value ) && URL to go to
m.szCmd = "" && Command to execute (RUN program)
IF ( ! EMPTY( m.szURL ) ) && If the URL was filled

m.szBrowser = HTTP_GetDefaultBrowser() && Locate the default browser
IF ( ! EMPTY( m.szBrowser ) ) && If we obtained something

HTML/HTTP Functions
m.nChoice = MNU_create( "Browser access" ) && Present a context menu
DO CASE && In function of the choice

CASE ( m.nChoice == CH_GO_WEB ) && Go web ?
m.szCmd = m.szBrowser + " " + m.szURL && Build the command to execute
ENDCASE
IF ( ! EMPTY( m.szCmd ) ) && If Command built (RUN <program>)

SYS_WinExec( m.szCmd ) && Execute program now
ENDIF
ELSE
m.oIE = CREATEOBJECT( m.szClass ) && Create an Internet Explorer
&& object
IF ( TYPE( "m.oIE" ) == "O" ) && If we could create the object
WITH m.oIE && With the IExplorer object

m.oIE.Navigate( m.szURL ) && Navigate to this URL
m.oIE.Visible = .T. && Make the thing visible
ENDWITH
ENDIF
ENDIF
ENDIF
HTTP_GetURL() : Retrieves URL as a string.

Remark
Proxies and firewalls are not supported for the time being. HTTP_GetURL() features a server timeout of 60 seconds:
if the server does not respond within 60 seconds, the request is aborted. The same applies when the server does not
send any more information within the same period.
Syntax
HTTP_GetURL( szURL[,nMemory] )  szStream
Parameters
szURL the URL to access.
nMemory optional parameter. If not passed, FOCUS.FLL will freeze some memory space for you. The
function operates quicker if you pass the memory to reserve to retrieve the Internet stream (a
page, a sound, an image, ...).
Returns
szStream Internet stream.
Example
&& Example #1
* This example copies the homepage of ORACLE into the clipboard
_CLIPTEXT = HTTP_GetURL( "http://www.oracle.com" )
* This will yield a string similar to:

<HTML>
<HEAD>
<NOSCRIPT>
<META HTTP-EQUIV="Refresh" CONTENT="0; URL=/admin/errors/js.html">
</NOSCRIPT>
<TITLE>Oracle Corporation</TITLE>
<SCRIPT LANGUAGE="JavaScript">
// Catch some browser error conditions
if (parseInt(navigator.appVersion.charAt(0) <= 3)) top.location.href =
"/admin/errors/version.html"
crumb = '<A HREF="/" target="_top">Home</A> > ';

header = '00';
country = 'US';

HTML/HTTP Functions
language = 'en';
</SCRIPT>
</HEAD>
<SCRIPT LANGUAGE="JavaScript" SRC="/admin/jscripts/lib.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/admin/jscripts/lang.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/admin/jscripts/frame.js"></SCRIPT>
<NOFRAMES>
<BODY>
If you can see this page, then either an error has occurred or your web browser does not
support some of the features of this web site. 
Either try reloading this page or click <A HREF="site_map.html">here</A> for more
information.
</BODY>
</NOFRAMES>
</HTML>
&& Example #2
LOCAL szWeb
LOCAL szNum
LOCAL szExt
&& This example will extract an image from FastWrite's web site. The image is
&& returned as a string. Then, the string is saved to a file thanks to
&& FIL_StringToFile() and finally, the background picture of VFP is set to the
&& newly created image file.
szWeb = "http://www.fastwrite.com/products/focus/Banners/Banner"
szNum = "001"
szExt = ".jpg"
szPath = "O:\SPOT2000"
_screen.picture = IIF( FIL_StringToFile( szPath + szNum + szExt , ;

HTTP_GetURL( szWeb + szNum + szExt ) ;
) , ;
szPath + szNum + szExt,"" )
See Also
HTTP_GetURL2() ., HTTP_PostURL()
HTTP_GetURL2() : Retrieves URL as a string.

Remark
Proxies and firewalls are not supported for the time being. HTTP_GetURL() features a server timeout of 60 seconds:
if the server does not respond within 60 seconds, the request is aborted. The same applies when the server does not
send any more information within the same period. This function does the same thing as HTTP_GetURL() . However,
it uses a totally different strategy by calling WININET.
Syntax
HTTP_GetURL2( szURL[,nMemory] )  szStream
Parameters
Returns
Example
&& Example #1
* This example copies the homepage of FastWrire into the clipboard
_CLIPTEXT = HTTP_GetURL2( "http://www.fastwrite.com" )
* This will yield a string similar to:

HTML/HTTP Functions
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML><HEAD><meta http-equiv="Refresh"
content="300"><meta name="revisit-after" content="15"><meta name="classification"
content="DVL,PROGRAMMER,DEVELOPER,DLL,WIN32,FOXPRO,VISUAL,FOCUS.FLL"><meta http-equiv="PICS-Label"
content='(PICS-1.1 "http://www.rsac.org/ratingsv01.html" l gen true comment "RSACi North America
Server" for "http://www.fastwrite.com" on "2000.08.03T20:55-0800" r (n 0 s 0 v 0 l
0))'><TITLE>FastWrite : Visual FoxPro, FOCUS.FLL, Consulting</TITLE><script
language="javascript1.2">
</script>
</HEAD>
<script language="JavaScript">
</script>
<link rel="stylesheet" type="text/css" href="http://www.fastwrite.com/styles/fw.css">
 <body rightmargin="0" leftmargin="0" topmargin="0" bottommargin="0"
marginwidth="0" marginheight="0" bgcolor="#A5A6D8" background=""><div id="overDiv"
style="position:absolute; visibility:hidden; z-index:1000;"></div><script language="JavaScript"
src="http://www.fastwrite.com/js/overlib.js"></script>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="762"><TR HEIGHT="30"><TD WIDTH="160"

VALIGN="middle" BGCOLOR="#A5A6D8" ALIGN="center"><DIV ID="BackHome"><A
HREF="http://www.fastwrite.com">Home</A></DIV></TD><TD VALIGN="middle"
BGCOLOR="#F7B21C"><DIV ID="MainMenu"><A HREF="http://www.fastwrite.com/products/products.cfm">Products</A> <IMG SRC="http://www.fastwrite.com/Images/separation.jpg"
BORDER="0"> <A
HREF="http://www.fastwrite.com/Products/Services.cfm">Services</A> <IMG
SRC="http://www.fastwrite.com/Images/separation.jpg" BORDER="0"> <A
HREF="http://www.fastwrite.com/products/focus/fll/focusfll.cfm">focus.fll</A> <IMG

HTML/HTTP Functions
HREF="http://www.fastwrite.com/products/FOCUS/VCX/FOCUSVCX.CFM">focus.vcx</A> <IMG
HREF="http://www.fastwrite.com/whatsnew.cfm">News</A> <IMG
HREF="http://www.fastwrite.com/members">Members</A> <IMG
verdana;font-size: 8pt;position: relative;top: -6px"> <A HREF="mailto:info@fastwrite.com">Contact
Us</A> <IMG SRC="http://www.fastwrite.com/Images/separation.jpg" BORDER="0"> <A
HREF="http://www.fastwrite.com/search.cfm">Search</A> <IMG
verdana;font-size: 8pt;position: relative;top: -6px"> </DIV></TD></TR><TR HEIGHT="600"><TD WIDTH="160" VALIGN="top" BGCOLOR="#A5A6D8"><DIV ID="NavMenu"><a href="" onClick="toggleStyle( 'Menu1' ); return false;"><IMG
SRC="http://www.fastwrite.com/Images/BranchesClose2.jpg" BORDER="0" NAME="imgMenu1">Products</a> 

 <a href="http://www.fastwrite.com/Products/Manage/Manage.cfm"
onmouseover="return overlib('All software that we have built to manage domestic
needs...',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">«I Manage...»</a> 
 <a href="http://www.fastwrite.com/Products/Focus/focus.cfm"

onmouseover="return overlib('The Dynamic Link Library for Visual FoxPro developers. More than 1900
functions!',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">FOCUS</a> 
 <a href="http://www.fastwrite.com/Products/tailor"

onmouseover="return overlib('All software that we have built for specific
customers',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Custom Made</a> 
 <a href="http://www.fastwrite.com/Products/penguin"

onmouseover="return overlib('Our Commercial Suite for mobile phones
shops',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Penguin</a> 
 <a href="http://www.fastwrite.com/Products/freetools"

onmouseover="return overlib('Free Utilities for
everybody',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Free utilities</a> 


<a href="" onClick="toggleStyle( 'Menu2' ); return false;"><IMG
class="MenuItem">Services</a> 


 <a href="http://www.fastwrite.com/Products/Services.cfm"
onmouseover="return overlib('Company Background, types of
services, ...',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return
nd();">Introduction</a> 
 <a href="http://www.fastwrite.com/Products/training.cfm"

onmouseover="return overlib('FastWrite organizes training for
developers',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Training</a> 
 <a href="http://www.fastwrite.com/Products/Hosting.cfm"

onmouseover="return overlib('FastWrite offers basic web hosting services. We do not have tons of
clients, and we want to keep it that way. But you can count on us to deliver a very customized range
of services to you.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return
nd();">Web Hosting</a> 
 <a href="http://www.fastwrite.com/Products/WebCons.cfm"

HTML/HTTP Functions
onmouseover="return overlib('What we have done for our own web site ... we can do it for
yours. Everything is programmed ... all the text is safely stored in a database and pages are built
on demand. All the images and graphics you see on our site have been handcrafted by
ourselves.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Web Development</a> 
 <a href="http://www.fastwrite.com/Products/WinDev.cfm"

onmouseover="return overlib('We cannot count the projects we have been into, both in Windows
and in Unix. Simply put, our software runs in some of the largest pharmaceutical plants, and in the
largest banks of the world. If we were good for them, we are surely good for the things we may have
to do for you.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return
nd();">Win & Unix</a> 
 <a
href="http://www.fastwrite.com/Products/maintenance.cfm">Hardware
Maintenance</a> 
href="http://www.fastwrite.com/Products/maintenance.cfm">Software
Maintenance</a> 


class="MenuItem">Tech Support</a> 

 <a href="http://www.fastwrite.com/TechSupp/Manage.cfm"
onmouseover="return overlib('Our collection of software for home: manage your CDs, your
books, your video tapes, your budget, your invoices, your
images, ....',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">I Manage</a> 
 <a href="http://www.fastwrite.com/TechSupp/Focus.cfm"

onmouseover="return overlib('A library constructed in C with more than 1900 functions for
the Visual FoxPro developer. This is the library that helped us constructing mission critical
applications in VFP for the largest pharmaceutical plants, and for the largest banks of the world.
This is the place to go for getting support on our
library.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">FOCUS</a> 
 <a href="http://www.fastwrite.com/TechSupp/hosting.cfm"

onmouseover="return overlib('Need support on our hosting services? This is the link to
follow.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Hosting</a> 


class="MenuItem">Legal</a> 

 <a href="http://www.fastwrite.com/Legal/ethic.cfm"
onmouseover="return overlib('Browse through our ethic code: you will see what you can expect from us
in terms of behavior and professional
services.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Ethic Code</a> 
 <a href="http://www.fastwrite.com/Legal/cgv.cfm"

onmouseover="return overlib('Read attentively our Sales
Condition.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Sales Conditions</a> 
 <a href="http://www.fastwrite.com/Legal/privacy.cfm"

onmouseover="return overlib('Curious about what we do with your personal data? Read our privacy
statement.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Privacy Statement</a> 
 <a href="http://www.fastwrite.com/Legal/docs.cfm"

onmouseover="return overlib('If you want to know who we are, what we do, our company, our statutes,
etc. ... here you can download ALL our legal
papers.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Legal documents</a> 


class="MenuItem">Press Room</a> 


HTML/HTTP Functions
 Press Releases 
 <a href="http://www.fastwrite.com/whatsnew.cfm">What's new?</a> 
 Newsletters 


class="MenuItem">Job Opportunities</a> 

 Current Opportunities 




class="MenuItem">Links</a> 

 <a href="http://www.fastwrite.com/Links/AllLinks.cfm">Browse</a> 
 <a href="http://www.fastwrite.com/AddLink.cfm">Add your link</a> 


class="MenuItem">Developers Area</a> 

 <a href="http://www.fastwrite.com/DvlOnly/General"
onmouseover="return overlib('Computer books review (Dr. Dobbs), Downloads, VFP resources,
etc.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">General</a> 
 <a href="http://www.fastwrite.com/DvlOnly/VFP"

onmouseover="return overlib('Articles for VFP developers, Download section, Tutorial about
FOCUS.FLL, Tutorial about FOCUS.VCX.',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');"
onmouseout="return nd();">Visual FoxPro</a> 
href="http://www.fastwrite.com/DvlOnly/general/downloadsonly.cfm" onmouseover="return
overlib('Resources to download from FastWrite\'s web
site',FGCOLOR,'#A5A6D8',BGCOLOR,'White',TEXTCOLOR,'White');" onmouseout="return nd();">Downloads</a> 


class="MenuItem">About us</a> 

 <a href="http://www.fastwrite.com/AboutUs/Belgium.cfm">Belgium</a> 



 
 
<TABLE BORDER="0" CELLPADDING="1" CELLSPACING="0" BGCOLOR="#8975B2"><TR><TD><TABLE border="0"

cellpadding="1" cellspacing="0">
<TR><TD WIDTH="14" NOWRAP BGCOLOR="#8975B2" HEIGHT="20"> </TD>
<TD WIDTH="144" NOWRAP BGCOLOR="#FFFFFF">


HTML/HTTP Functions
<A HREF="HTTP://WWW.FASTWRITE.COM/SENDFILE.CFM?
file=F:/PROTECTEDRESOURCES/FASTWRITEWEB/EXTRANET/PUBLIC/FOCUS803S.ZIP" onclick="return true;">FOCUS
8.03</A>
 
</TD></TR></TABLE></TD></TR></TABLE>
 
</DIV></TD><TD VALIGN="top" BGCOLOR="#9A97C7" BACKGROUND=""><DIV
ID="Body"><script type="text/javascript"
src="http://www.fastwrite.com/scripts/snow.js"></script>
Welcome
<table WIDTH="100%" BORDER="0">

<TR>
<TD>

 <IMG SRC="http://www.fastwrite.com/Images/FromOurOffice.jpg"
ALIGN="Left">
Happy New Year Everyone! Hope you and your loved ones had a safe and wonderful New Year. 
We have promised to release the sources of FOCUS.FLL before New Year.
Unfortunately, we are still busy making modifications to the sources of FOCUS.FLL, version 8.04! Therefore, we kindly ask you to wait a
little bit. Thank you.


</TD>
</TR>
</table>


FOCUS 8.04
Version 8.04 of FOCUS.FLL is in preparation. We plan to deliver new
compression functions (that would permit to compress multiple files at once), new printer functions
that would provide a lot more details on the jobs submitted to a specific printer, and resume our
work about the communication functions (COM_*()). 
Some other functions related to the NT File System will appear also. For example the ability to
create a logical link to a file and refer to that link later on (similar to UNIX): it makes it a lot
easier to "share" files between instances of your applications. Well ... and more. Stay tuned. 



FOCUS 8.03
FOCUS.FLL 8.03 is available. It contains a number of bug fixes as
well as about 12 new functions. 
What's new?
1. LOG_Append(): internal bug fixed when strategy set to "Reduce
to Half Size". 
2. EnumWindows(): this was an internal alias of WIN_EnumChildren(). This is no longer the case as it became the alias of WIN_EnumWindows(). Potential code impact. 
3. GetWindows(): this was an internal alias of WIN_GetChildren(). This is no longer the case as it became the alias of WIN_GetWindows(). Potential code impact. 
4. WIN_EnumWindows(): new function. No code impact. Initiates the
retrieval of a list of top-level windows of Windows. 
5. WIN_GetWindows(): new function. No code impact. Completes the
retrieval of the list of the top-level windows started via WIN_EnumWindows(). 

HTML/HTTP Functions
6. WIN_BringWindowToTop(): new function. No code impact. Was kept
internal to FOCUS.FLL. We have finally decided to document it. 
7. SYS_GlobalMemoryStatus(): bug fix. The size returned by the
function couldn't fit large memories (as much as 1 Gb, or even more) as we find in the computers
nowadays. The visible effect was that the number returned by the function was a negative number.
This has been corrected to return a positive number instead. Potential code impact. 
8. SYS_ExitProcess(): new function. Makes it possible to return
an error level to the calling application or command file. No code impact. 
9. TIM_MakeTime(): Correction of a vicious bug that happened when
the function was called at a moment when the local time expression was laying into another day than
the GMT time (for example GMT is 23PM and local time is 01AM). Potential code impact. 
10. ARR_average(): Correction of a bug with one-dimensional
arrays. Potential code impact. 
11. MET_FeetToMeters(): a metric function to convert feet to
meters. New function. No code impact. 
12. MET_MetersToFeet(): a metric function to convert meters to
feet. New function. No code impact. 
13. NUM_gcd(): Euclid's implementation of the greatest common
divisor of two integers. New function. No code impact. 
14. NUM_UniversalID(): creates a globally unique identifier of 66
bytes maximum. Use this function when you need an absolutely unique number that you will use as a
persistent identifier in a distributed environment. To a very high degree of certainty, this
function returns a unique value - no other invocation, on the same or any other system (networked or
not), should return the same value. The algorithm that is followed assures that the ID is unique in
space and unique in time. 
15. The Test Status grid of each function has been removed from the documentation. 
16. All Font functions are gone (FNT_*()) as we
announced in 2002. 
17. All User functions are gone (USR_*()) as we
announced in 2002. 

Registered Users

Version 8.03 is available for download from the Members section: simply prepare your login
information ...
<a href="http://www.fastwrite.com/members/members.cfm">Go to login screen</a>



Efficient Data Hiding in VFP
For sure you came across the need to maintain some data hidden from your users, either because you
really want to protected them against messing up with your appication, or simply because you keep
some keys secret. 
Sounds familiar? You bet! What we do usually is to encrypt the contents of the file, hide it in a
place known by us, and access this file whenever we have to. 
Well ... on NTFS drives ... there is a better alternative: "Named
Streams" 
We confess that this possibility has been around from some time, but it has been downplayed by
Microsoft. This is unfortunate because streams can be incredibly useful in many situations. And
streams are easy to use! 
As a first attempt, let's create a stream in a command shell (you'll see how easy it is):
<pre class="SrcCode">
D:\>echo "Hello FOCUS" > MYFILE.TXT:MYSTREAM
D:\>dir *.txt
Volume in drive D is CONSTELLATION_D
Volume Serial Number is E44E-4E1A
Directory of D:\
12/01/2003 15:55 0 MYFILE.TXT

1 File(s) 0 bytes
0 Dir(s) 10.097.905.664 bytes free
</pre>

HTML/HTTP Functions
What one can immediately see is that the file is reported having a size of 0 bytes! Amazing, isn't
it? 
Now ... try to see what's in the file:
D:\>MORE < MYFILE.TXT
</pre>
Nothing is reported!

D:\>MORE < MYFILE.TXT:MYSTREAM
"Hello FOCUS"
</pre>
The first attempt with MORE < MYFILE.TXT didn't render what was
stored in the file. However, the second attempt, MORE <
MYFILE.TXT:MYSTREAM, did! Woaw! 
Is there any way to do this in a programmatic way? YES! ... with FOCUS.FLL! Try the following code ... it will just do the same:
#define WIN32API_STRATEGY 1
LOCAL nHandle
FIL_SetOpenStrategy( WIN32API_STRATEGY )
m.nHandle = FIL_create( "D:\MYFILE.TXT:MYSTREAM",GENERIC_READ+GENERIC_WRITE )
FIL_write( m.nHandle,["Hello FOCUS"] )
FIL_close( m.nHandle )
</pre>
Even the Explorer will report a length of 0 bytes! 
I think that you have the idea, now. Simply use the powerful File functions of FOCUS.FLL to play with NTFS to its fullest potential. 
For those of you that want to know more about Data Streams, they can follow this link:
<a href ="http://www.microsoft.com/technet/treeview/default.asp?
url=/technet/prodtechnol/winxppro/reskit/prkc_fil_xurt.asp">Microsoft</a>
</DIV></TD></TR><DIV ID="FWPageFooter"><TR><TD WIDTH="160" VALIGN="top"
BGCOLOR="#A5A6D8"> </TD><TD><TABLE CELLPADDING="0" CELLSPACING="0" WIDTH="100%"><TR><TD
HEIGHT="3"></TD></TR><TR><TD
BACKGROUND="http://www.fastwrite.com/Images/Orange.png"></TD></TR><TR><TD ALIGN="RIGHT"
BGCOLOR="#9A97C7" HEIGHT="17" VALIGN="middle"><A
HREF="http://www.fastwrite.com"><IMG SRC="http://www.fastwrite.com/Images/LittleFW2.jpg" BORDER="0"
ALT="Design by FastWrite" WIDTH="77" HEIGHT="21" ALIGN="LEFT"></A><IMG
SRC="http://www.fastwrite.com/Images/frv.png" BORDER="0" ALT="Not yet active" WIDTH="21" HEIGHT="21"
ALIGN="LEFT"><IMG SRC="http://www.fastwrite.com/Images/nlv.png" BORDER="0" ALT="Not yet active"
WIDTH="21" HEIGHT="21" ALIGN="LEFT"><IMG SRC="http://www.fastwrite.com/Images/env.png" BORDER="0"
ALT="Not yet active" WIDTH="21" HEIGHT="21" ALIGN="LEFT"><IMG
SRC="http://www.fastwrite.com/Images/dev.png" BORDER="0" ALT="Not yet active" WIDTH="21" HEIGHT="21"
ALIGN="LEFT"><A HREF="http://www.fastwrite.com">Home</A> - <A
HREF="http://www.fastwrite.com/comments.cfm">Comments</A> - <A
HREF="http://www.fastwrite.com/Legal/Legal.cfm">Copyright © 2000 -
All Rights Reserved.</A> <A HREF="mailto:info@fastwrite.com"><IMG
SRC="http://www.fastwrite.com/Images/envelope.gif" BORDER="0" ALT="Quick touch with
us"></A></TD></TR><TR><TD
BACKGROUND="http://www.fastwrite.com/Images/Orange.png"></TD></TD></TR></DIV></TABLE></BODY></HTML>
See Also
HTTP_GetURL() ., HTTP_PostURL()

HTML/HTTP Functions
HTTP_InternetDial() : Initiates a connection to the Internet
using a modem.
Syntax
HTTP_InternetDial( szDialUp[,dwFlags] )  lSuccess
Parameters
szDialUp dial-up connection to use.
dwFlags optional parameter. Unsigned long integer value that contains the flags to use. This can be one
of the following values: INTERNET_AUTODIAL_FORCE_ONLINE (0x0001) = Forces an online
connection. INTERNET_AUTODIAL_FORCE_UNATTENDED (0x0002) = Forces an unattended
Internet dial-up. If user intervention is required, the function will fail.
INTERNET_DIAL_FORCE_PROMPT = Ignores the "dial automatically" setting and forces the
dialing user interface to be displayed. INTERNET_DIAL_UNATTENDED (0x8000) = Connects to
the Internet through a modem, without displaying a user interface, if possible. Otherwise, the
function will wait for user input. INTERNET_DIAL_SHOW_OFFLINE = Shows the Work Offline
button instead of Cancel button in the dialing user interface.
Returns
dwConnection connection handle or 0 if the function failed.
Example
IF ( HTTP_InternetDial( "Yucom" ) )
szHome = HTTP_GetURL( "http://www.oracle.com" )
ENDIF
HTTP_IsURL() : Returns status information about a URL.

Remarks
The HTTP_IsURL() function makes it possible to determine almost any kind of information available about a
resource. Not only can you determine whether a resource is available but you can also determine the resource type, or

HTML/HTTP Functions
the resource length (if available). For example, by querying a resource with the HTTP_QUERY_STATUS_CODE , you
can determine whether the resource is available (200 ... OK). Querying the same resource with
HTTP_QUERY_CONTENT_TYPE permits to be sure that the specified resource is of the desired type (a jpeg image for
example). Then querying the content length thanks to HTTP_QUERY_CONTENT_LENGTH will inform you about the size
of the image!
Syntax
HTTP_IsURL( szDomain,szPath[,nType] )  szStatus
Parameters
szDomain the base host name (use HTTP_CrackURL() to split a URL into a domain and a path).
szPath the path (use HTTP_CrackURL() to split a URL into a domain and a path).
nType optional parameter. The type of information to query.
HTTP 1.0 defined headers

#define HTTP_QUERY_MIME_VERSION 0
#define HTTP_QUERY_CONTENT_TYPE 1
#define HTTP_QUERY_CONTENT_TRANSFER_ENCODING 2
#define HTTP_QUERY_CONTENT_ID 3
#define HTTP_QUERY_CONTENT_DESCRIPTION 4
#define HTTP_QUERY_CONTENT_LENGTH 5
#define HTTP_QUERY_CONTENT_LANGUAGE 6
#define HTTP_QUERY_ALLOW 7
#define HTTP_QUERY_PUBLIC 8
#define HTTP_QUERY_DATE 9
#define HTTP_QUERY_EXPIRES 10
#define HTTP_QUERY_LAST_MODIFIED 11
#define HTTP_QUERY_MESSAGE_ID 12
#define HTTP_QUERY_URI 13
#define HTTP_QUERY_DERIVED_FROM 14
#define HTTP_QUERY_COST 15
#define HTTP_QUERY_LINK 16
#define HTTP_QUERY_PRAGMA 17
#define HTTP_QUERY_VERSION 18
#define HTTP_QUERY_STATUS_TEXT 20
#define HTTP_QUERY_RAW_HEADERS 21
#define HTTP_QUERY_RAW_HEADERS_CRLF 22
#define HTTP_QUERY_CONNECTION 23
#define HTTP_QUERY_ACCEPT 24
#define HTTP_QUERY_ACCEPT_CHARSET 25
#define HTTP_QUERY_ACCEPT_ENCODING 26
#define HTTP_QUERY_ACCEPT_LANGUAGE 27
#define HTTP_QUERY_AUTHORIZATION 28
#define HTTP_QUERY_CONTENT_ENCODING 29
#define HTTP_QUERY_FORWARDED 30
#define HTTP_QUERY_FROM 31
#define HTTP_QUERY_IF_MODIFIED_SINCE 32
#define HTTP_QUERY_LOCATION 33
#define HTTP_QUERY_ORIG_URI 34
#define HTTP_QUERY_REFERER 35
#define HTTP_QUERY_RETRY_AFTER 36
#define HTTP_QUERY_SERVER 37
#define HTTP_QUERY_TITLE 38
#define HTTP_QUERY_USER_AGENT 39
#define HTTP_QUERY_WWW_AUTHENTICATE 40
#define HTTP_QUERY_PROXY_AUTHENTICATE 41
#define HTTP_QUERY_ACCEPT_RANGES 42
#define HTTP_QUERY_SET_COOKIE 43
#define HTTP_QUERY_COOKIE 44
#define HTTP_QUERY_REQUEST_METHOD 45
#define HTTP_QUERY_REFRESH 46
#define HTTP_QUERY_CONTENT_DISPOSITION 47

HTML/HTTP Functions
HTTP 1.1 defined headers
#define HTTP_QUERY_AGE 48
#define HTTP_QUERY_CACHE_CONTROL 49
#define HTTP_QUERY_CONTENT_BASE 50
#define HTTP_QUERY_CONTENT_LOCATION 51
#define HTTP_QUERY_CONTENT_MD5 52
#define HTTP_QUERY_CONTENT_RANGE 53
#define HTTP_QUERY_ETAG 54
#define HTTP_QUERY_HOST 55
#define HTTP_QUERY_IF_MATCH 56
#define HTTP_QUERY_IF_NONE_MATCH 57
#define HTTP_QUERY_IF_RANGE 58
#define HTTP_QUERY_IF_UNMODIFIED_SINCE 59
#define HTTP_QUERY_MAX_FORWARDS 60
#define HTTP_QUERY_PROXY_AUTHORIZATION 61
#define HTTP_QUERY_RANGE 62
#define HTTP_QUERY_TRANSFER_ENCODING 63
#define HTTP_QUERY_UPGRADE 64
#define HTTP_QUERY_VARY 65
#define HTTP_QUERY_VIA 66
#define HTTP_QUERY_WARNING 67
The following list contains the values and corresponding constants for the HTTP status codes
returned by servers on the Internet
HTTP Status Codes

Constant Value Description
HTTP_STATUS_OK 200 The request completed successfully.
HTTP_STATUS_CREATED 201 The request has been fulfilled and resulted in
the creation of a new resource.
HTTP_STATUS_ACCEPTED 202 The request has been accepted for processing ,
but the processing has not been completed.
HTTP_STATUS_PARTIAL 203 The returned meta information in the entity-
header is not the definitive set available from
the origin server.
HTTP_STATUS_NO_CONTENT 204 The server has fulfilled the request, but there is
no new information to send back.
HTTP_STATUS_RESET_CONTENT 205 The request has been completed, and the client
program should reset the document view that
caused the request to be sent to allow the user
to easily initiate another input action.
HTTP_STATUS_PARTIAL_CONTENT 206 The server has fulfilled the partial GET request
for the resource.
HTTP_STATUS_AMBIGUOUS 300 The server couldn't decide what to return.
HTTP_STATUS_MOVED 301 The requested resource has been assigned to a
new permanent URI, and any future references
to this resource should be done using one of the
returned URIs.
HTTP_STATUS_REDIRECT 302 The requested resource resides temporarily
under a different URI.
HTTP_STATUS_REDIRECT_METHOD 303 The response to the request can be found under
a different URI and should be retrieved using a
GET method on that resource.
HTTP_STATUS_NOT_MODIFIED 304 The requested resource has not been modified.
HTTP_STATUS_USE_PROXY 305 The requested resource must be accessed
through the proxy given by the location field.
HTTP_STATUS_REDIRECT_KEEP_VERB 307 The redirected request keeps the same verb.
HTTP/1.1 behavior.
HTTP_STATUS_BAD_REQUEST 400 The request could not be processed by the
server due to invalid syntax.
HTTP_STATUS_DENIED 401 The requested resource requires user
authentication.
HTTP_STATUS_PAYMENT_REQ 402 Not currently implemented in the HTTP protocol.
HTTP_STATUS_FORBIDDEN 403 The server understood the request, but is
refusing to fulfill it.
HTTP_STATUS_NOT_FOUND 404 The server has not found anything matching the
requested URI.
HTTP_STATUS_BAD_METHOD 405 The method used is not allowed.
HTTP_STATUS_NONE_ACCEPTABLE 406 No responses acceptable to the client were

HTML/HTTP Functions
found.
HTTP_STATUS_PROXY_AUTH_REQ 407 Proxy authentication required.
HTTP_STATUS_REQUEST_TIMEOUT 408 The server timed out waiting for the request.
HTTP_STATUS_CONFLICT 409 The request could not be completed due to a
conflict with the current state of the resource.
The user should resubmit with more information.
HTTP_STATUS_GONE 410 The requested resource is no longer available at
the server, and no forwarding address is known.
HTTP_STATUS_LENGTH_REQUIRED 411 The server refuses to accept the request without
a defined content length.
HTTP_STATUS_PRECOND_FAILED 412 The precondition given in one or more of the
request header fields evaluated to false when it
was tested on the server.
HTTP_STATUS_REQUEST_TOO_LARGE 413 The server is refusing to process a request
because the request entity is larger than the
server is willing or able to process.
HTTP_STATUS_URI_TOO_LONG 414 The server is refusing to service the request
because the request URI is longer than the
server is willing to interpret.
HTTP_STATUS_UNSUPPORTED_MEDIA 415 The server is refusing to service the request
because the entity of the request is in a format
not supported by the requested resource for the
requested method.
HTTP_STATUS_SERVER_ERROR 500 The server encountered an unexpected condition
that prevented it from fulfilling the request.
HTTP_STATUS_NOT_SUPPORTED 501 The server does not support the functionality
required to fulfill the request.
HTTP_STATUS_BAD_GATEWAY 502 The server, while acting as a gateway or proxy,
received an invalid response from the upstream
server it accessed in attempting to fulfill the
request.
HTTP_STATUS_SERVICE_UNAVAIL 503 The service is temporarily overloaded.
HTTP_STATUS_GATEWAY_TIMEOUT 504 The request was timed out waiting for a
gateway.
HTTP_STATUS_VERSION_NOT_SUP 505 The server does not support, or refuses to
support, the HTTP protocol version that was
used in the request message.
Returns
szStatus request status.
Example
LOCAL szDomain
LOCAL szPath
LOCAL szStatus
&& Let's split the URL into a domain name and a path
&& For example, http://www.fastwrite.com/images/BannerVFP.jpg is the complete URL
&& szDomain = HTTP_CrackURL( szFull,0 ) -> "www.fastwrite.com"

&& szPath = HTTP_CrackURL( szFull,1 ) -> "/images/BannerVFP.jpg"
szDomain = HTTP_CrackURL( szURL,0 ) && Get the host name

szPath = HTTP_CrackURL( szURL,1 ) && Get the path
&& Now ... let's ask FOCUS.FLL whether that resource exist
szStatus = HTTP_IsURL( szDomain,szPath,HTTP_QUERY_STATUS_CODE )
&& "200" means OK; 404 means page not found; 403 means Forbidden ... these codes
&& are the same as the ones used in Internet Explorer
IF ( szStatus != "200" )
? "Resource exists!"
ENDIF

HTML/HTTP Functions
HTTP_LastError() : Last error encountered in HTTP functions.
Syntax
HTTP_LastError()  szLastError
Parameters
None.
Returns
szLastError last error that occurred while using the HTTP_*() functions.
Example
IF ( EMPTY( HTTP_GetURL( "http://www.fastwrite.com" ) ) )
? "Cannot open FastWrite home page.",HTTP_LastError()
ENDIF
HTTP_LastGetURLTime() : Returns the time the last

HTTP_GetURL() operation in milliseconds.
Syntax
HTTP_LastGetURLTime()  nMilliseconds
Parameters
None.
Returns
nMilliSeconds time of the last HTTP_GetURL() in milliseconds.
Example
* This example attempts to retrieve homepages for Oracle, Sybase and Microsoft
* Then ... based on the number of bytes sent over and the time taken for the
* operation to complete, it establishes the transfer rate:
szOracle = HTTP_GetURL("http://www.oracle.com" )
nOracle = HTTP_LastGetURLTime()
szSybase = HTTP_GetURL("http://www.sybase.com" )
nSybase = HTTP_LastGetURLTime()
szMS = HTTP_GetURL("http://www.microsoft.com" )
nMS = HTTP_LastGetURLTime()
? LEN( szOracle ) / ( nOracle/1000 ),"bytes per second"

? LEN( szSybase ) / ( nSybase/1000 ),"bytes per second"
? LEN( szMS ) / ( nMS/1000 ),"bytes per second"
HTTP_LastVersion() : Returns the file stamp of HTTP functions.

Remark

HTML/HTTP Functions
Syntax
HTTP_LastVersion()  szLastVersion
Parameters
None.
Returns
HTTP_PostURL() : Gets URL and posts information.

Syntax
HTTP_PostURL( szURL,szPost )  szStream
Parameters
szPost the post block to pass in the HTTP request.
Returns
Example
LOCAL szUserName
LOCAL szPassword
LOCAL szPost
m.szUserName = "Jean Desmet"

m.szPassword = "trnhgtyw"
&& The POST request has to be formatted as if the parameters

&& were passed as part of the URL. Parameters are separated
&& by an ampersand (&)
m.szPost = "user=" + m.szUserName + "&";
"pwd=" + m.szPassword
szHTML = HTTP_PostURL( "http://www.site.com/Login.cfm",m.szPost )
&& What's in szHTML now is the response of the server
See Also
HTTP_GetURL() .
HTTP_SetCallback() : Gets/Sets a callback function for the

HTTP_GetURL*() functions.
Syntax
HTTP_SetCallback( [szFunc] )  szCurFunc
Parameters
szFunc the new callback function. This function should return a logical value, .T. or .F.. If it returns
.F., the current download initiated by HTTP_GetURL() or HTTP_GetURL2() is aborted.

HTML/HTTP Functions
Returns
szCurFunc the current callback function.
Example
LOCAL szCallback
szCallback = HTTP_SetCallback( "HTTPCallback()" )
<... here you would have code that calls the HTTP_GetURL() function >
&& When done, we reset the callback to what it was

HTTP_SetCallback( szCallback )
FUNCTION HTTPCallback()
LOCAL lRetVal
&& Check if F12 was pressed. In that case, abort the

&& current download started by HTTP_GetURL()
m.lRetVal = ( INKEY("H") != 134 ) && F12 ?
RETURN ( m.lRetVal )
HTTP_SetURLTimeout() : Gets/Sets the timeout value used in

HTTP functions.
Syntax
HTTP_SetURLTimeout( [nMilliSeconds] )  nCurMilliSeconds
Parameters
nMilliSeconds the new timeout in milliseconds. This parameter is optional.
Returns
nCurMilliSeconds the current setting in milliseconds.
Example
LOCAL nMilli
LOCAL szHTML
m.nMilli = HTTP_SetURLTimeout( 30000 ) && Save the old setting

m.szHTML = HTTP_GetURL( "http://www.fastwrite.com" )
IF ( EMPTY( m.szHTML ) )
? "The server is not responding"
ENDIF
HTTP_SetURLTimeout( m.nMilli ) && Restore the old setting
HTTP_URLDecode() : Decodes a URL.

Alias
HTTP_DecodeURL(), URLDecode(), DecodeURL() .
Syntax
HTTP_URLDecode( szURL )  szDecodedURL

HTML/HTTP Functions
Parameters
szURL URL to encode.
Returns
szDecodedURL the decoded URL.
Example
? HTTP_URLEncode( "http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this is a test" )
&& Result ...
&& http%3a%2f%2fwww.fastwrite.com%2fdynafox.fxp%3factive%3dTrue%26pattern%3dthis+is+a+test
? HTTP_URLEncode( "http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this is a test",.F. )

&& Result ...
&& http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this+is+a+test
? HTTP_URLDecode( "http%3a%2f%2fwww.fastwrite.com%2fdynafox.fxp%3factive%3dTrue%26pattern%3dthis+is+a+test" )
&& Result ...
&& http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this is a test
? HTTP_UrlDecode( "http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this+is+a+test" )
&& Result ...
See Also
HTTP_URLEncode() , HTTP_canonicalizeURL() .
HTTP_URLEncode() : Encodes a URL.

Alias
HTTP_EncodeURL(), URLEncode(), EncodeURL() .
Syntax
HTTP_URLEncode( szURL[,lStrict] )  szEncodedURL
Parameters
szURL URL to encode.
lStrict Optional parameter. .T. by default. If passed and set to .F. , then the following characters are
replicated as they are in the original stream: ':', '/', '?', '&', and '=' .
Returns
szEncodedURL the encoded URL.
Example
? HTTP_URLEncode( "http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this is a test" )
&& Result ...
&& http%3a%2f%2fwww.fastwrite.com%2fdynafox.fxp%3factive%3dTrue%26pattern%3dthis+is+a+test
? HTTP_URLEncode( "http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this is a test",.F. )

&& Result ...
&& http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this+is+a+test
? HTTP_URLDecode( "http%3a%2f%2fwww.fastwrite.com%2fdynafox.fxp%3factive%3dTrue%26pattern%3dthis+is+a+test" )
&& Result ...
? HTTP_UrlDecode( "http://www.fastwrite.com/dynafox.fxp?active=True&pattern=this+is+a+test" )
&& Result ...
See Also
HTTP_URLDecode() , HTTP_canonicalizeURL() .

INI Functions
INI File Functions

INI Functions
Functions Synopsis
We decided to assign aliases to INI functions for the sake of convenience. All these functions are in fact available
under the File category of FOCUS.
As LANs become increasingly popular, programmers need to ensure their applications will run properly in a network
environment. In order to do this, they’ll have to consider their applications shared by multiple users, each of them
wanting to preserve personal preferences.
Many applications use configuration files in the same directory as the executable file to retain settings that were used
from one program session to another.
In a network application, it is highly recommended to use INI files instead. Windows comes with a set of profile
functions whose goal is to store user-specific information. The profile functions create initialization files in one user’s
private Windows directory. These functions fall into two categories : those that access the WIN.INI file and those that
access other .INI files.
FOCUS provides few functions to read and write both the WIN.INI or any other .INI file.
READ WRITE
WIN.INI GetProfileString() WriteProfileString()
*.INI GetPrivateProfileString() WritePrivateProfileString()
In addition to these basic services, FOCUS makes it also possible to read an entire .INI section :
WIN.INI GetProfileSection()
*.INI GetPrivateProfileSection()

INI Functions
GetPrivateProfileString() : Reads a character string from an .INI file.
Alias
FIL_reaini(), FIL_ReadIni() .
Syntax
GetPrivateProfileString( szSection,szEntry,szINIFile )  szString
Parameters
szSection section of .INI file.
szINIFile .INI file name.
Returns
Example
IF ( GetPrivateProfileString( "SECRET" , ;
"PassWord" , ;
"MY.INI" ;
) != cPassWord ;
)
ENDIF
GetPrivateProfileSection() : Reads .INI section.

Syntax
GetPrivateProfileSection( szSection,szINIFile )  cEntries
Parameters
szINIFile .INI file to read from.
Returns
cEntries all entries for given section. Up to 1024 bytes.
Example
? "Wallpaper settings",GetPrivateProfileSection( "wallpaper","myapp.ini" )
GetProfileSection() : Reads WIN.INI section.

Syntax
GetProfileSection( szSection )  cEntries
Parameters

INI Functions
Returns
cEntries all entries for given section.
Example
? "Printer list",GetProfileSection( "devices" )
GetProfileString() : Reads a character string from the WIN.INI

file.
Syntax
GetProfileString( szSection,szEntry )  szString
Parameters
Returns
Example
IF ( GetProfileString( "MYAPP","PassWord" ) <> cPassWord )
ENDIF
WritePrivateProfileString() : Copies a character string into a

.INI file.
Alias
Syntax
WritePrivateProfileString( szSection,szEntry.NULL.,szString.NULL.,szINIFile )  lSuccess
Parameters
szSection section of the .INI file to write to.
szEntry key name that appears under the section name. If this parameter is an empty string ( "") or a
.NULL. , the section is deleted from the .INI file.
szString string to write to .INI file. If this parameter is an empty string ( "") or a .NULL. , the entry is
deleted from the .INI file.
szINIFile .INI file name.
Returns
Example
IF ( ! WritePrivateProfileString( "WALLPAPER" , ;
"Fill file" , ;
"FILLER.BMP", ;

INI Functions
"MYAPP.INI" ;
) ;
)
ENDIF
WriteProfileString() : Copies a character string into the WIN.INI

file.
Syntax
WriteProfileString( szSection,szEntry,szString )  lSuccess
Parameters
szString string to write to WIN.INI file.
Returns
Example
IF ( ! WriteProfileString( "MYAPP","Desktop","640 480 256" ) )
ENDIF

IP Functions
IP Functions

IP Functions
IP_GetAddress() : Returns the IP address of the PC.

Alias
GetIPAddress()
Syntax
IP_GetAddress()  szAddresses
Parameters
None.
Returns
szAddresses a tokenized string of addresses. Only the first token is meaningful.
Example
? IP_GetAddress() && 169.254.90.109^0.0.0.0^0.0.0.0^0.0.0.0^0.0.0.0^
IP_GetIP() : Returns the IP address corresponding to a given

domain name.
Alias
gethostbyname(), HTTP_GetIP(), HTTP_GetHostByName()
Syntax
IP_GetIP( szDomain )  szIP
Parameters
szDomain the domain for which the IP addresses should be returned.
Returns
szIP a tokenized string of IP addresses corresponding to the szDomain domain name. Each IP
address is separated by a caret (^).
Example
? IP_GetIP( "www.microsoft.com" ) && 207.191.213.230^
? IP_GetIP( "orion" ) && 192.168.254.2 (machine on local network)
P_LastError() : Determines the last error that occurred within

the IP_*() functions.
Syntax
IP_LastError()  szLastError
Parameters
None.

IP Functions
Returns
szLastError string describing the last error that occurred using the IP_*() functions.
IP_LastVersion() : Returns the file stamp of IP functions.

Remark
Syntax
IP_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\IP.C-Mon Oct 19 15:55:22 1998" .
IP_ping() : Pings to an IP address

Syntax
IP_ping( szIP|szHost )  lSuccess
Parameters
None.
Returns
szIP a string that forms a valid IP address
or
szHost a string that forms a host name
Example
? IP_ping( "217.136.220.21" ) && .T.
? IP_ping( "www.fastwrite.com" ) && .T.
? IP_ping( "www.fastwrite.cof" ) && .F. (domain name error)
? IP_ping( "http://www.fastwrite.com" ) && .F. (no http in front!)

Keyboard Functions
Keyboard Functions

Keyboard Functions
KEY_CodePage() : Retrieves the OEM code-page identifier for

the system.
Comment
This functions has been placed in the Keyboard section because of the GetKBCodePage() function of Windows 3.1.
GetKBCodePage() has now been replaced by GetOEMCP(), available under Windows NT and
Windows 95.
Syntax
KEY_CodePage()  nCodePage
Parameters
None.
Returns
nCodePage OEM code-page identifier, or it is the default identifier if the registry value is not readable.
Following are the OEM code-page identifiers:
Identifier Meaning
437 MS-DOS United States
850 MS-DOS Multilingual (Latin I)
852 MS-DOS Slavic (Latin II)
855 IBM Cyrillic (primarily Russian)
857 IBM Turkish
860 MS-DOS Portuguese
861 MS-DOS Icelandic
863 MS-DOS Canadian-French
865 MS-DOS Nordic
866 MS-DOS Russian (former USSR)
869 IBM Modern Greek
KEY_fast() : Sets the keyboard tick speed to its max.

Syntax
KEY_fast()  .T.
Parameters
None.
Returns
.T. the function always returns a logical .T..
Example
IF ( FIL_reaini( "KEYBOARD","Speed","MYAPP.INI" ) = "FAST" )
KEY_fast()
ENDIF

Keyboard Functions
KEY_fmax() : Returns the number of function keys on the
keyboard.
Syntax
KEY_fmax()  nFnctKeys
Parameters
None
Returns
nFnctKeys indicates the number of function keys on the keyboard.
Example
IF ( KEY_fmax() < 12 )
? "Enhanced keyboard required"
ENDIF
KEY_GetLayoutName() : Retrieves the name of the active

keyboard layout.
Syntax
KEY_GetLayoutName()  cLayout
Parameters
None.
Returns
cLayout keyboard layout name.
Example
? KEY_GetLayoutName() && 000080c
KEY_HookF12() : Captures the F12 key.

Remark
Please notice that the F12 key will only be captured at the level of the running application and not at the system level.
Syntax
KEY_HookF12( [szCmd] )  lSuccess
Parameters
szCmd The command that must be executed whenever the F12 is pressed. This parameter is optional.
Returns
lSuccess .T. if the F12 key is successfully captured; .F. if not.

Keyboard Functions
Example
&& Example #1
KEY_HookF12Proc( "WAIT WINDOW 'Hello' NOWAIT" )
IF ( KEY_HookF12() )
? "Each time you press the F12 key, the 'Hello' message will be displayed"
ENDIF
&& Example #2
IF ( KEY_HookF12( "WAIT WINDOW 'Bonjour' NOWAIT" ) )
? "Each time you press the F12 key, the 'Bonjour' message will be displayed"
ENDIF
KEY_HookF12Proc() : Customizes the command to be

executed when the F12 key is pressed.
Remark
Please notice that the F12 key will only be captured at the level of the running application and not at the system level.
The command associated to the F12 key will be played back even if pressed during an intensive VFP code such as a
loop.
Syntax
KEY_HookF12Proc( szCmd )  .T.
Parameters
None.
Returns
.T. always.
Example
&& Example #1
KEY_HookF12Proc( "WAIT WINDOW 'Hello' NOWAIT" )
IF ( KEY_HookF12() )
? "Each time you press the F12 key, the 'Hello' message will be displayed"
ENDIF
&& Example #2
&& This will show you how to use the KEY_HookF12() key
&& to interrupt a code intensive loop
PRIVATE lStopScanning
m.lStopScanning = .F.
USE myBigFile
KEY_HookF12Proc( "DO StopScanning" )
SCAN FOR ( ! m.lStopScanning )

WAIT WINDOW ALLTRIM( STR( RECNO() ) ) NOWAIT
ENDSCAN
PROCEDURE StopScanning()
m.lStopScanning = .T.
RETURN

Keyboard Functions
KEY_HookPrtScr() : Captures the PrintScreen key.
Remark
Please notice that the PrintScreen key will only be captured at the level of the running application and not at the
system level.
Syntax
KEY_HookPrtScr( [szCmd] )  lSuccess
Parameters
szCmd The command that must be executed whenever the PrintScreen is pressed. This parameter is
optional.
Returns
lSuccess .T. if the PrintScreen key is successfully captured; .F. if not.
Example
&& Example #1
KEY_HookPrtScrProc( "WAIT WINDOW 'Hello' NOWAIT" )
IF ( KEY_HookPrtScr() )
? "Each time you press the PrintScreen key, the 'Hello' message will be displayed"
ENDIF
&& Example #2
IF ( KEY_HookPrtScr( "WAIT WINDOW 'Bonjour' NOWAIT" ) )
? "Each time you press the PrintScreen key, the 'Bonjour' message will be displayed"
ENDIF
KEY_HookPrtScrProc() : Customizes the command to be

executed when the PrintScreen key is pressed.
Remark
Please notice that the PrintScreen key will only be captured at the level of the running application and not at the
system level.
Syntax
KEY_HookPrtScrProc( szCmd )  .T.
Parameters
None.
Returns
.T. always.
Example
KEY_HookPrtScrProc( "WAIT WINDOW 'Hello' NOWAIT" )
IF ( KEY_HookPrtScr() )
? "Each time you press the PrintScreen key, the 'Hello' message will be displayed"
ENDIF

Keyboard Functions
KEY_iscaps() : returns the current status of the CapsLock key.
Syntax
KEY_iscaps()  lStatus
Parameters
None.
Returns
lStatus .T. if CapsLock ON; .F. if OFF.
KEY_IsShift() : Determines whether a shift key (left or right) is

down.
Syntax
KEY_IsShift()  lStatus
Parameters
None.
Returns
lStatus .T. if Shift key down; .F. if not.
KEY_IsLShift() : Determines whether the left shift key is down.

Syntax
KEY_IsLShift()  lStatus
Parameters
None.
Returns
lStatus .T. if Left Shift key down; .F. if not.
KEY_IsRShift() : Determines whether the right shift key is

down.
Syntax
KEY_IsRShift()  lStatus
Parameters
None.

Keyboard Functions
Returns
lStatus .T. if Right Shift key down; .F. if not.
KEY_IsCtrl() : Determines whether a control key (left or right)

is down.
Syntax
KEY_IsCtrl()  lStatus
Parameters
None.
Returns
lStatus .T. if Ctrl key down; .F. if not.
KEY_IsLCtrl() : Determines whether the left control key is

down.
Syntax
KEY_IsLCtrl()  lStatus
Parameters
None.
Returns
lStatus .T. if Left Ctrl key down; .F. if not.
KEY_IsRCtrl() : Determines whether the right control key is

down.
Syntax
KEY_IsRCtrl()  lStatus
Parameters
None.
Returns
lStatus .T. if Right Ctrl key down; .F. if not.
KEY_IsAlt() : Determines whether a alt key (left or right) is

down.
Syntax
KEY_IsAlt()  lStatus

Keyboard Functions
Parameters
None.
Returns
lStatus .T. if Alt key down; .F. if not.
KEY_IsLAlt() : Determines whether the left alt key is down.

Syntax
KEY_IsLAlt()  lStatus
Parameters
None.
Returns
lStatus .T. if Left Alt key down; .F. if not.
KEY_IsRAlt() : Determines whether the right altl key is down.

Syntax
KEY_IsRAlt()  lStatus
Parameters
None.
Returns
lStatus .T. if Right Alt key down; .F. if not.
KEY_isins() : Returns the current status of the Ins key.

Syntax
KEY_isins()  lStatus
Parameters
None.
Returns
lStatus .T. if Ins ON; .F. if OFF.
KEY_isnum() : Returns the current status of the NumLock key.

Syntax
KEY_isnum()  lStatus

Keyboard Functions
Parameters
None.
Returns
lStatus .T. if NumLock ON; .F. if OFF.
KEY_IsScrl() : Returns the current status of the ScrollLock key.

Syntax
KEY_isscrl()  lStatus
Parameters
None.
Returns
lStatus .T. if ScrollLock ON; .F. if OFF.
KEY_LastVersion() : Returns the file stamp of KEY functions.

Remark
Syntax
KEY_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\KEYBOARD.C-Mon Oct 19 15:55:22 1998" .
KEY_norm() : Sets the keyboard tick speed to its normal

cruise.
Syntax
KEY_norm()  .T.
Parameters
None.
Returns

Keyboard Functions
Example
IF ( FIL_reaini( "KEYBOARD","Speed","MYAPP.INI" ) = "NORMAL" )
KEY_norm()
ENDIF
KEY_SetCap() : Sets the current status of the CapsLock key.

Syntax
KEY_setcap( lSetting )  .T.
Parameters
lSetting .T. to set the CapsLock ON; .F. to turn it off.
Returns
KEY_SetNum() : Sets the current status of the NumLock key.

Syntax
KEY_SetNum( lSetting )  .T.
Parameters
lSetting .T. to set the NumLock key ON; .F. to turn it off.
Returns
KEY_SetScr() : Sets the current status of the ScrollLock key.

Syntax
KEY_SetScr( lSetting )  .T.
Parameters
lSetting .T. to set the ScrollLock key ON; .F. to turn it off.
Returns
KEY_slow() : Sets the keyboard tick speed to its slowest

speed.
Syntax
KEY_slow()  .T.
Parameters
None.

Keyboard Functions
Returns
Example
IF ( FIL_reaini( "KEYBOARD","Speed","APP.INI" ) = "VERY SLOW" )
KEY_slow()
ENDIF
KEY_type() : Retrieves information about the current keyboard.

Syntax
KEY_type( [nSetting] )  nKBDInfo
Parameters
nSetting specifies the type of keyboard information to be retrieved.
Value Meaning
0 Keyboard type
1 Keyboard subtype
2 Number of function keys on the keyboard
Returns
nKBDInfo if the function succeeds, the return value specifies the requested information. If the function
fails, the return value is zero.
SubType
Identifier Meaning
1 IBM® PC/XT® ( ) or compatible (83-key) keyboard
2 Olivetti® "ICO" (102-key) keyboard
3 IBM PC/AT® (84-key) or similar keyboard
4 IBM enhanced (101- or 102-key) keyboard
5 Nokia® 1050 and similar keyboards
6 Nokia 9140 and similar keyboards
7 Japanese keyboard
Function keys
Identifier Meaning
1 10
2 12 (sometimes 18)
3 10
4 12
5 10
6 24
7 Hardware dependent and specified by the OEM
KEY_UnHookF12() : Releases the capture of the PrintScreen

key.
Syntax
KEY_UnHookPrtScreenProc()  .T.

Keyboard Functions
Parameters
None.
Returns
.T. always.
KEY_UnHookPrtScr() : Releases the capture of the PrintScreen

key.
Syntax
KEY_UnHookPrtScreenProc()  .T.
Parameters
None.
Returns
.T. always.

Kernel Functions
Kernel Functions

Kernel Functions
Functions Synopsis
The kernel functions are related to the KERNEL.DLL Dynamic Linked Library of FOCUS.FLL . This DLL, provides some
cross-language facilities in FOCUS.FLL .
Many services of FOCUS.FLL do come from the kernel and as time goes by, we intend to place more and more
functions in the kernel so that they would be callable from any language that has an access to DLLs.

Kernel Functions
KNL_major() : Returns the major version number of

KERNEL.DLL.
Syntax
KNL_major()  nMajor
Parameters
None.
Returns
nMajor major version number.
KNL_minor() : Returns the minor version number of

KERNEL.DLL.
Syntax
KNL_minor()  nMinor
Parameters
None.
Returns
nMinor minor version number.
KNL_vers() : Returns the version number of KERNEL.DLL.

Syntax
KNL_vers()  szVersion
Parameters
None.
Returns
szVersion version number identifier.
Example
? MIS_knlvers() && "KERNEL.DLL - Pat Boens - 17 June 1998 18:45-v3.0"

Language Functions
Language Setting Functions

Language Functions
LNG_LastVersion() : Returns the file stamp of LNG functions.

Remark
Syntax
LNG_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\LANGUAGE.C-Mon Oct 19 15:55:22 1998" .
LNG_MakeLangID() : constructs a language ID from a primary

language ID and a sublanguage ID.
Syntax
LNL_MakeLangID( nPrimary,nSub )  nLanguage
Parameters
nPrimary primary language ID.
LANG_NEUTRAL 0x00
LANG_AFRIKAANS 0x36
LANG_ALBANIAN 0x1c
LANG_ARABIC 0x01
LANG_BASQUE 0x2d
LANG_BELARUSIAN 0x23
LANG_BULGARIAN 0x02
LANG_CATALAN 0x03
LANG_CHINESE 0x04
LANG_CROATIAN 0x1a
LANG_CZECH 0x05
LANG_DANISH 0x06
LANG_DUTCH 0x13
LANG_ENGLISH 0x09
LANG_ESTONIAN 0x25
LANG_FAEROESE 0x38
LANG_FARSI 0x29
LANG_FINNISH 0x0b
LANG_FRENCH 0x0c
LANG_GERMAN 0x07
LANG_GREEK 0x08
LANG_HEBREW 0x0d
LANG_HUNGARIAN 0x0e
LANG_ICELANDIC 0x0f
LANG_INDONESIAN 0x21
LANG_ITALIAN 0x10
LANG_JAPANESE 0x11
LANG_KOREAN 0x12
LANG_LATVIAN 0x26
LANG_LITHUANIAN 0x27
LANG_NORWEGIAN 0x14
LANG_POLISH 0x15
LANG_PORTUGUESE 0x16
LANG_ROMANIAN 0x18
LANG_RUSSIAN 0x19
LANG_SERBIAN 0x1a
LANG_SLOVAK 0x1b
LANG_SLOVENIAN 0x24

Language Functions
LANG_SPANISH 0x0a
LANG_SWEDISH 0x1d
LANG_THAI 0x1e
LANG_TURKISH 0x1f
LANG_UKRAINIAN 0x22
LANG_VIETNAMESE 0x2a
nSub sublanguage ID.

SUBLANG_NEUTRAL 0x00 language neutral
SUBLANG_ARABIC_SAUDI_ARABIA 0x01 Arabic (Saudi Arabia)
SUBLANG_ARABIC_IRAQ 0x02 Arabic (Iraq)
SUBLANG_ARABIC_EGYPT 0x03 Arabic (Egypt)
SUBLANG_ARABIC_LIBYA 0x04 Arabic (Libya)
SUBLANG_ARABIC_ALGERIA 0x05 Arabic (Algeria)
SUBLANG_ARABIC_MOROCCO 0x06 Arabic (Morocco)
SUBLANG_ARABIC_TUNISIA 0x07 Arabic (Tunisia)
SUBLANG_ARABIC_OMAN 0x08 Arabic (Oman)
SUBLANG_ARABIC_YEMEN 0x09 Arabic (Yemen)
SUBLANG_ARABIC_SYRIA 0x0a Arabic (Syria)
SUBLANG_ARABIC_JORDAN 0x0b Arabic (Jordan)
SUBLANG_ARABIC_LEBANON 0x0c Arabic (Lebanon)
SUBLANG_ARABIC_KUWAIT 0x0d Arabic (Kuwait)
SUBLANG_ARABIC_UAE 0x0e Arabic (U.A.E)
SUBLANG_ARABIC_BAHRAIN 0x0f Arabic (Bahrain)
SUBLANG_ARABIC_QATAR 0x10 Arabic (Qatar)
SUBLANG_CHINESE_TRADITIONAL 0x01 Chinese (Taiwan)
SUBLANG_CHINESE_SIMPLIFIED 0x02 Chinese (PR China)
SUBLANG_CHINESE_HONGKONG 0x03 Chinese (Hong Kong)
SUBLANG_CHINESE_SINGAPORE 0x04 Chinese (Singapore)
SUBLANG_DUTCH 0x01 Dutch
SUBLANG_DUTCH_BELGIAN 0x02 Dutch (Belgian)
SUBLANG_ENGLISH_US 0x01 English (USA)
SUBLANG_ENGLISH_UK 0x02 English (UK)
SUBLANG_ENGLISH_AUS 0x03 English (Australian)
SUBLANG_ENGLISH_CAN 0x04 English (Canadian)
SUBLANG_ENGLISH_NZ 0x05 English (New Zealand)
SUBLANG_ENGLISH_EIRE 0x06 English (Irish)
SUBLANG_ENGLISH_SOUTH_AFRICA 0x07 English (South Africa)
SUBLANG_ENGLISH_JAMAICA 0x08 English (Jamaica)
SUBLANG_ENGLISH_CARIBBEAN 0x09 English (Caribbean)
SUBLANG_ENGLISH_BELIZE 0x0a English (Belize)
SUBLANG_ENGLISH_TRINIDAD 0x0b English (Trinidad)
SUBLANG_FRENCH 0x01 French
SUBLANG_FRENCH_BELGIAN 0x02 French (Belgian)
SUBLANG_FRENCH_CANADIAN 0x03 French (Canadian)
SUBLANG_FRENCH_SWISS 0x04 French (Swiss)
SUBLANG_FRENCH_LUXEMBOURG 0x05 French (Luxembourg)
SUBLANG_GERMAN 0x01 German
SUBLANG_GERMAN_SWISS 0x02 German (Swiss)
SUBLANG_GERMAN_AUSTRIAN 0x03 German (Austrian)
SUBLANG_GERMAN_LUXEMBOURG 0x04 German (Luxembourg)
SUBLANG_GERMAN_LIECHTENSTEIN 0x05 German (Liechtenstein)
SUBLANG_ITALIAN 0x01 Italian
SUBLANG_ITALIAN_SWISS 0x02 Italian (Swiss)
SUBLANG_KOREAN 0x01 Korean (Extended Wansung)
SUBLANG_KOREAN_JOHAB 0x02 Korean (Johab)
SUBLANG_NORWEGIAN_BOKMAL 0x01 Norwegian (Bokmal)
SUBLANG_NORWEGIAN_NYNORSK 0x02 Norwegian (Nynorsk)
SUBLANG_PORTUGUESE 0x02 Portuguese
SUBLANG_PORTUGUESE_BRAZILIAN 0x01 Portuguese (Brazilian)
SUBLANG_SERBIAN_LATIN 0x02 Serbian (Latin)
SUBLANG_SERBIAN_CYRILLIC 0x03 Serbian (Cyrillic)
SUBLANG_SPANISH 0x01 Spanish (Castilian)
SUBLANG_SPANISH_MEXICAN 0x02 Spanish (Mexican)
SUBLANG_SPANISH_MODERN 0x03 Spanish (Modern)
SUBLANG_SPANISH_GUATEMALA 0x04 Spanish (Guatemala)
SUBLANG_SPANISH_COSTA_RICA 0x05 Spanish (Costa Rica)
SUBLANG_SPANISH_PANAMA 0x06 Spanish (Panama)
SUBLANG_SPANISH_DOMINICAN_REPUBLIC 0x07 Spanish (Dominican Republic)
SUBLANG_SPANISH_VENEZUELA 0x08 Spanish (Venezuela)
SUBLANG_SPANISH_COLOMBIA 0x09 Spanish (Colombia)
SUBLANG_SPANISH_PERU 0x0a Spanish (Peru)
SUBLANG_SPANISH_ARGENTINA 0x0b Spanish (Argentina)
SUBLANG_SPANISH_ECUADOR 0x0c Spanish (Ecuador)
SUBLANG_SPANISH_CHILE 0x0d Spanish (Chile)
SUBLANG_SPANISH_URUGUAY 0x0e Spanish (Uruguay)
SUBLANG_SPANISH_PARAGUAY 0x0f Spanish (Paraguay)
SUBLANG_SPANISH_BOLIVIA 0x10 Spanish (Bolivia)
SUBLANG_SPANISH_EL_SALVADOR 0x11 Spanish (El Salvador)
SUBLANG_SPANISH_HONDURAS 0x12 Spanish (Honduras)
SUBLANG_SPANISH_NICARAGUA 0x13 Spanish (Nicaragua)
SUBLANG_SPANISH_PUERTO_RICO 0x14 Spanish (Puerto Rico)
SUBLANG_SWEDISH 0x01 Swedish
SUBLANG_SWEDISH_FINLAND 0x02 Swedish (Finland)

Language Functions
Returns
nLanguage language ID.
Hexa Decimal Language

0x0401 1025 Arabic
0x0402 1026 Bulgarian
0x0403 1027 Catalan
0x0404 1028 Traditional Chinese
0x0804 2052 Simplified Chinese
0x0405 1029 Czech
0x0406 1030 Danish
0x0407 1031 German
0x0807 2055 Swiss German
0x0408 1032 Greek
0x0409 1033 U.S. English
0x0809 2057 U.K. English
0x040A 1034 Castilian Spanish
0x080A 2058 Mexican Spanish
0x040B 1035 Finnish
0x040C 1036 French
0x080C 2060 Belgian French
0x0C0C 3084 Canadian French
0x100C 4108 Swiss French
0x040D 1037 Hebrew
0x040E 1038 Hungarian
0x040F 1039 Icelandic
0x0410 1040 Italian
0x0810 2064 Swiss Italian
0x0411 1041 Japanese
0x0412 1042 Korean
0x0413 1043 Dutch
0x0813 2067 Belgian Dutch
0x0414 1044 Norwegian ¥ BokmÕl
0x0814 2068 Norwegian ¥ Nynorsk
0x0415 1045 Polish
0x0416 1046 Brazilian Portuguese
0x0816 2070 Portuguese
0x0417 1047 Rhaeto-Romanic
0x0418 1048 Romanian
0x0419 1049 Russian
0x041A 1050 Croato-Serbian (Latin)
0x081A 2074 Serbo-Croatian (Cyrillic)
0x041B 1051 Slovak
0x041C 1052 Albanian
0x041D 1053 Swedish
0x041E 1054 Thai
0x041F 1055 Turkish
0x0420 1056 Urdu
0x0421 1057 Bahasa
Example
&& Forming a Belgian Dutch language identifier
? LNG_MakeLangID( 0x13,2 ) && 2067
&& Forming a Belgian French language identifier
? LNG_MakeLangID( 0x12,2 ) && 2060
LNG_set() : Gets/sets the internal language code

Syntax
LNG_set( [nLngCode] )  nCurLngCode
Parameters
nLngCode internal language code.
Returns
nCurLngCode the current internal language code.
0x0401 1025 Arabic

0x0403 1027 Catalan

Language Functions
0x0405 1029 Czech
0x0406 1030 Danish
0x0407 1031 German
0x0408 1032 Greek
0x040B 1035 Finnish
0x040C 1036 French
0x040D 1037 Hebrew
0x0410 1040 Italian
0x0412 1042 Korean
0x0413 1043 Dutch
0x0415 1045 Polish
0x0419 1049 Russian
0x041B 1051 Slovak
0x041D 1053 Swedish
0x041E 1054 Thai
0x041F 1055 Turkish
0x0420 1056 Urdu
0x0421 1057 Bahasa
Example
#define NIL .NULL.
FUNCTION InitApp()
=LNG_set( 1 )
<any other code that is to placed in the init stage>
RETURN ( NIL )
FUNCTION ChangeLng( nSetting )

IF ( PARAMETERS() == 1 )
=LNG_set( nSetting )
ELSE
=LNG_set( LNG_set() + 1 )
ENDIF
RETURN ( NIL )
FUNCTION Example()
LOCAL nLng
LOCAL cMessage
nLng = LNG_set()
DO CASE
CASE ( nLng == 1 )
cMessage = "Hello World"
CASE ( nLng == 2 )
cMessage = "Bonjour tout le monde"
CASE <etc.>
<other code>
ENDCASE
RETURN

Locale Functions
Locale Settings

Locale Functions
LOC_EnumSystemLocales() : Enumerates the locales that are

installed on a system.
Remark
LOC_EnumSystemLocales() must be used prior to call the SYS_GetSystemLocales() function of FOCUS.FLL .
This function is of valuable help used in conjunction with the WIN_MsgBox() function.
Alias
EnumSystemLocales() .
Syntax
LOC_EnumSystemLocales()  lSuccess
Parameters
None.
Returns
lSuccess .T. if the function succeeds; .F. otherwise.
Example
IF ( LOC_EnumSystemLocales() )
? "Installed locales:",LOC_GetSystemLocales()
ENDIF
LOC_GetLocaleSetting() : Returns a locale setting

Syntax
LOC_GetLocaleSetting( nLCType )  szSetting
Parameters
nLCType information type.
MANIFEST CONSTANT HEX DESCRIPTION

LOCALE_ILANGUAGE 0x00000001 language id
LOCALE_SLANGUAGE 0x00000002 localized name of language
LOCALE_SENGLANGUAGE 0x00001001 English name of language
LOCALE_SABBREVLANGNAME 0x00000003 abbreviated language name
LOCALE_SNATIVELANGNAME 0x00000004 native name of language
LOCALE_ICOUNTRY 0x00000005 country code
LOCALE_SCOUNTRY 0x00000006 localized name of country
LOCALE_SENGCOUNTRY 0x00001002 English name of country
LOCALE_SABBREVCTRYNAME 0x00000007 abbreviated country name
LOCALE_SNATIVECTRYNAME 0x00000008 native name of country
LOCALE_IDEFAULTLANGUAGE 0x00000009 default language id
LOCALE_IDEFAULTCOUNTRY 0x0000000A default country code
LOCALE_IDEFAULTCODEPAGE 0x0000000B default oem code page
LOCALE_IDEFAULTANSICODEPAGE 0x00001004 default ansi code page
LOCALE_SLIST 0x0000000C list item separator
LOCALE_IMEASURE 0x0000000D 0 = metric; 1 = US
LOCALE_SDECIMAL 0x0000000E decimal separator
LOCALE_STHOUSAND 0x0000000F thousand separator
LOCALE_SGROUPING 0x00000010 digit grouping
LOCALE_IDIGITS 0x00000011 number of fractional digits
LOCALE_ILZERO 0x00000012 leading zeros for decimal
LOCALE_INEGNUMBER 0x00001010 negative number mode
LOCALE_SNATIVEDIGITS 0x00000013 native ascii 0-9
LOCALE_SCURRENCY 0x00000014 local monetary symbol
LOCALE_SINTLSYMBOL 0x00000015 intl monetary symbol

Locale Functions
LOCALE_SMONDECIMALSEP 0x00000016 monetary decimal separator
LOCALE_SMONTHOUSANDSEP 0x00000017 monetary thousand separator
LOCALE_SMONGROUPING 0x00000018 monetary grouping
LOCALE_ICURRDIGITS 0x00000019 # local monetary digits
LOCALE_IINTLCURRDIGITS 0x0000001A # intl monetary digits
LOCALE_ICURRENCY 0x0000001B positive currency mode
LOCALE_INEGCURR 0x0000001C negative currency mode
LOCALE_SDATE 0x0000001D date separator
LOCALE_STIME 0x0000001E time separator
LOCALE_SSHORTDATE 0x0000001F short date format string
LOCALE_SLONGDATE 0x00000020 long date format string
LOCALE_STIMEFORMAT 0x00001003 time format string
LOCALE_IDATE 0x00000021 short date format ordering
LOCALE_ILDATE 0x00000022 long date format ordering
LOCALE_ITIME 0x00000023 time format specifier
LOCALE_ITIMEMARKPOSN 0x00001005 time marker position
LOCALE_ICENTURY 0x00000024 century format specifier (short date)
LOCALE_ITLZERO 0x00000025 leading zeros in time field
LOCALE_IDAYLZERO 0x00000026 leading zeros in day field (short date)
LOCALE_IMONLZERO 0x00000027 leading zeros in month field (short date)
LOCALE_S1159 0x00000028 AM designator
LOCALE_S2359 0x00000029 PM designator
LOCALE_ICALENDARTYPE 0x00001009 type of calendar specifier
LOCALE_IOPTIONALCALENDAR 0x0000100B additional calendar types specifier
LOCALE_IFIRSTDAYOFWEEK 0x0000100C first day of week specifier
LOCALE_IFIRSTWEEKOFYEAR 0x0000100D first week of year specifier
LOCALE_SDAYNAME1 0x0000002A long name for Monday
LOCALE_SDAYNAME2 0x0000002B long name for Tuesday
LOCALE_SDAYNAME3 0x0000002C long name for Wednesday
LOCALE_SDAYNAME4 0x0000002D long name for Thursday
LOCALE_SDAYNAME5 0x0000002E long name for Friday
LOCALE_SDAYNAME6 0x0000002F long name for Saturday
LOCALE_SDAYNAME7 0x00000030 long name for Sunday
LOCALE_SABBREVDAYNAME1 0x00000031 abbreviated name for Monday
LOCALE_SABBREVDAYNAME2 0x00000032 abbreviated name for Tuesday
LOCALE_SABBREVDAYNAME3 0x00000033 abbreviated name for Wednesday
LOCALE_SABBREVDAYNAME4 0x00000034 abbreviated name for Thursday
LOCALE_SABBREVDAYNAME5 0x00000035 abbreviated name for Friday
LOCALE_SABBREVDAYNAME6 0x00000036 abbreviated name for Saturday
LOCALE_SABBREVDAYNAME7 0x00000037 abbreviated name for Sunday
LOCALE_SMONTHNAME1 0x00000038 long name for January
LOCALE_SMONTHNAME2 0x00000039 long name for February
LOCALE_SMONTHNAME3 0x0000003A long name for March
LOCALE_SMONTHNAME4 0x0000003B long name for April
LOCALE_SMONTHNAME5 0x0000003C long name for May
LOCALE_SMONTHNAME6 0x0000003D long name for June
LOCALE_SMONTHNAME7 0x0000003E long name for July
LOCALE_SMONTHNAME8 0x0000003F long name for August
LOCALE_SMONTHNAME9 0x00000040 long name for September
LOCALE_SMONTHNAME10 0x00000041 long name for October
LOCALE_SMONTHNAME11 0x00000042 long name for November
LOCALE_SMONTHNAME12 0x00000043 long name for December
LOCALE_SMONTHNAME13 0x0000100E long name for 13th month, if any
LOCALE_SABBREVMONTHNAME1 0x00000044 abbreviated name for January
LOCALE_SABBREVMONTHNAME2 0x00000045 abbreviated name for February
LOCALE_SABBREVMONTHNAME3 0x00000046 abbreviated name for March
LOCALE_SABBREVMONTHNAME4 0x00000047 abbreviated name for April
LOCALE_SABBREVMONTHNAME5 0x00000048 abbreviated name for May
LOCALE_SABBREVMONTHNAME6 0x00000049 abbreviated name for June
LOCALE_SABBREVMONTHNAME7 0x0000004A abbreviated name for July
LOCALE_SABBREVMONTHNAME8 0x0000004B abbreviated name for August
LOCALE_SABBREVMONTHNAME9 0x0000004C abbreviated name for September
LOCALE_SABBREVMONTHNAME10 0x0000004D abbreviated name for October
LOCALE_SABBREVMONTHNAME11 0x0000004E abbreviated name for November
LOCALE_SABBREVMONTHNAME12 0x0000004F abbreviated name for December
LOCALE_SABBREVMONTHNAME13 0x0000100F abbreviated name for 13th month, if any
LOCALE_SPOSITIVESIGN 0x00000050 positive sign
LOCALE_SNEGATIVESIGN 0x00000051 negative sign
LOCALE_IPOSSIGNPOSN 0x00000052 positive sign position
LOCALE_INEGSIGNPOSN 0x00000053 negative sign position
LOCALE_IPOSSYMPRECEDES 0x00000054 mon sym precedes pos amt
LOCALE_IPOSSEPBYSPACE 0x00000055 mon sym sep by space from pos amt
LOCALE_INEGSYMPRECEDES 0x00000056 mon sym precedes neg amt
LOCALE_INEGSEPBYSPACE 0x00000057 mon sym sep by space from neg amt
Returns
szSetting locale setting.
Example
? LOC_GetLocaleSetting( 2 ) && "French (Belgian)"
? LOC_GetLocaleSetting( 6 ) && "Belgium"
? LOC_GetLocaleSetting( 8 ) && "Belgique"

Locale Functions
? LOC_GetLocaleSetting( 10 ) && "32"
? LOC_GetLocaleSetting( 21 ) && "BEF"
? LOC_GetLocaleSetting( NUM_htoi( "2A" ) ) && "lundi"
? LOC_GetLocaleSetting( NUM_htoi( "2B" ) ) && "mardi"
? LOC_GetLocaleSetting( NUM_htoi( "2C" ) ) && "mercredi"
? LOC_GetLocaleSetting( NUM_htoi( "2D" ) ) && "jeudi"
? LOC_GetLocaleSetting( NUM_htoi( "2E" ) ) && "vendredi"
? LOC_GetLocaleSetting( NUM_htoi( "2F" ) ) && "samedi"
? LOC_GetLocaleSetting( NUM_htoi( "30" ) ) && "dimanche"
? LOC_GetLocaleSetting( NUM_htoi( "31" ) ) && "lun."
? LOC_GetLocaleSetting( NUM_htoi( "32" ) ) && "mar."
<...>
? LOC_GetLocaleSetting( NUM_htoi( "38" ) ) && "janvier"
<...>
LOC_GetSystemLocales() : Gets the locales that were

enumerated via the LOC_EnumSystemLocales() function.
Remark
LOC_EnumSystemLocales() must be used prior to call the SYS_GetSystemLocales() function of FOCUS.FLL .
This function is of valuable help used in conjunction with the WIN_MsgBox() function.
Alias
GetSystemLocales() .
Syntax
LOC_GetSystemLocales()  szLocales
Parameters
None.
Returns
szLocales a string of installed locales.
Example
IF ( LOC_EnumSystemLocales() )
? "Installed locales:",LOC_GetSystemLocales()
ENDIF
LOC_GetUserDefaultLanguage() : Retrieves the user default

language identifier.
Syntax
LOC_GetUserDefaultLanguage()  nLanguage
Parameters
None.
Returns
nLanguage current language.

Locale Functions
0x0401 1025 Arabic
0x0403 1027 Catalan
0x0405 1029 Czech
0x0406 1030 Danish
0x0407 1031 German
0x0408 1032 Greek
0x040B 1035 Finnish
0x040C 1036 French
0x040D 1037 Hebrew
0x0410 1040 Italian
0x0412 1042 Korean
0x0413 1043 Dutch
0x0415 1045 Polish
0x0419 1049 Russian
0x041B 1051 Slovak
0x041D 1053 Swedish
0x041E 1054 Thai
0x041F 1055 Turkish
0x0420 1056 Urdu
0x0421 1057 Bahasa
Example
IF ( LOC_GetUserDefaultLanguage() == 2060 )
? "Belgian French. Correct?"
ENDIF
or ...
LOCAL nLanguage
nLanguage = LOC_GetUserDefaultLanguage()
IF ( NUM_hexa( nLanguage ) == "813" )

? "Belgian Dutch. Correct?"
ENDIF
LOC_GetUserPrimaryLanguage() : Extracts a primary language

identifier from a language identifier.
Syntax
LOC_GetUserPrimaryLanguage( [nLanguage] )  nPrimaryLanguage
Parameters
nLanguage language identifier to extract the primary identifier from. This parameter is optional. If it's not
passed, the LOC_GetUserPrimaryLanguage() function uses the default user language
identifier.

Locale Functions
Returns
nPrimaryLanguage primary language identifier. This is one of the following values:
LANG_NEUTRAL 0x00
LANG_AFRIKAANS 0x36
LANG_ALBANIAN 0x1c
LANG_ARABIC 0x01
LANG_BASQUE 0x2d
LANG_BELARUSIAN 0x23
LANG_BULGARIAN 0x02
LANG_CATALAN 0x03
LANG_CHINESE 0x04
LANG_CROATIAN 0x1a
LANG_CZECH 0x05
LANG_DANISH 0x06
LANG_DUTCH 0x13
LANG_ENGLISH 0x09
LANG_ESTONIAN 0x25
LANG_FAEROESE 0x38
LANG_FARSI 0x29
LANG_FINNISH 0x0b
LANG_FRENCH 0x0c
LANG_GERMAN 0x07
LANG_GREEK 0x08
LANG_HEBREW 0x0d
LANG_HUNGARIAN 0x0e
LANG_ICELANDIC 0x0f
LANG_INDONESIAN 0x21
LANG_ITALIAN 0x10
LANG_JAPANESE 0x11
LANG_KOREAN 0x12
LANG_LATVIAN 0x26
LANG_LITHUANIAN 0x27
LANG_NORWEGIAN 0x14
LANG_POLISH 0x15
LANG_PORTUGUESE 0x16
LANG_ROMANIAN 0x18
LANG_RUSSIAN 0x19
LANG_SERBIAN 0x1a
LANG_SLOVAK 0x1b
LANG_SLOVENIAN 0x24
LANG_SPANISH 0x0a
LANG_SWEDISH 0x1d
LANG_THAI 0x1e
LANG_TURKISH 0x1f
LANG_UKRAINIAN 0x22
LANG_VIETNAMESE 0x2a
Example
#define LANG_FRENCH 0x0c
IF ( LOC_GetUserPrimaryLanguage() == LANG_FRENCH )
? "Le message est en Français"
ELSE
? "The message is in English"
ENDIF
LOC_GetUserSubLanguage() : Extracts a sublanguage

identifier from a language identifier.
Syntax
LOC_GetUserSubLanguage( [nLanguage] )  nSubLanguage
Parameters
nLanguage language identifier to extract the sub identifier from. This parameter is optional. If it's not
passed, the LOC_GetUserSubLanguage() function uses the default user language identifier.
Returns
nSubLanguage sublanguage identifier. This is one of the following values :
SUBLANG_NEUTRAL 0x00 language neutral

Locale Functions
SUBLANG_ARABIC_SAUDI_ARABIA 0x01 Arabic (Saudi Arabia)
SUBLANG_ARABIC_IRAQ 0x02 Arabic (Iraq)
SUBLANG_ARABIC_EGYPT 0x03 Arabic (Egypt)
SUBLANG_ARABIC_LIBYA 0x04 Arabic (Libya)
SUBLANG_ARABIC_ALGERIA 0x05 Arabic (Algeria)
SUBLANG_ARABIC_MOROCCO 0x06 Arabic (Morocco)
SUBLANG_ARABIC_TUNISIA 0x07 Arabic (Tunisia)
SUBLANG_ARABIC_OMAN 0x08 Arabic (Oman)
SUBLANG_ARABIC_YEMEN 0x09 Arabic (Yemen)
SUBLANG_ARABIC_SYRIA 0x0a Arabic (Syria)
SUBLANG_ARABIC_JORDAN 0x0b Arabic (Jordan)
SUBLANG_ARABIC_LEBANON 0x0c Arabic (Lebanon)
SUBLANG_ARABIC_KUWAIT 0x0d Arabic (Kuwait)
SUBLANG_ARABIC_UAE 0x0e Arabic (U.A.E)
SUBLANG_ARABIC_BAHRAIN 0x0f Arabic (Bahrain)
SUBLANG_ARABIC_QATAR 0x10 Arabic (Qatar)
SUBLANG_CHINESE_TRADITIONAL 0x01 Chinese (Taiwan)
SUBLANG_CHINESE_SIMPLIFIED 0x02 Chinese (PR China)
SUBLANG_CHINESE_HONGKONG 0x03 Chinese (Hong Kong)
SUBLANG_CHINESE_SINGAPORE 0x04 Chinese (Singapore)
SUBLANG_DUTCH 0x01 Dutch
SUBLANG_DUTCH_BELGIAN 0x02 Dutch (Belgian)
SUBLANG_ENGLISH_US 0x01 English (USA)
SUBLANG_ENGLISH_UK 0x02 English (UK)
SUBLANG_ENGLISH_AUS 0x03 English (Australian)
SUBLANG_ENGLISH_CAN 0x04 English (Canadian)
SUBLANG_ENGLISH_NZ 0x05 English (New Zealand)
SUBLANG_ENGLISH_EIRE 0x06 English (Irish)
SUBLANG_ENGLISH_SOUTH_AFRICA 0x07 English (South Africa)
SUBLANG_ENGLISH_JAMAICA 0x08 English (Jamaica)
SUBLANG_ENGLISH_CARIBBEAN 0x09 English (Caribbean)
SUBLANG_ENGLISH_BELIZE 0x0a English (Belize)
SUBLANG_ENGLISH_TRINIDAD 0x0b English (Trinidad)
SUBLANG_FRENCH 0x01 French
SUBLANG_FRENCH_BELGIAN 0x02 French (Belgian)
SUBLANG_FRENCH_CANADIAN 0x03 French (Canadian)
SUBLANG_FRENCH_SWISS 0x04 French (Swiss)
SUBLANG_FRENCH_LUXEMBOURG 0x05 French (Luxembourg)
SUBLANG_GERMAN 0x01 German
SUBLANG_GERMAN_SWISS 0x02 German (Swiss)
SUBLANG_GERMAN_AUSTRIAN 0x03 German (Austrian)
SUBLANG_GERMAN_LUXEMBOURG 0x04 German (Luxembourg)
SUBLANG_GERMAN_LIECHTENSTEIN 0x05 German (Liechtenstein)
SUBLANG_ITALIAN 0x01 Italian
SUBLANG_ITALIAN_SWISS 0x02 Italian (Swiss)
SUBLANG_KOREAN 0x01 Korean (Extended Wansung)
SUBLANG_KOREAN_JOHAB 0x02 Korean (Johab)
SUBLANG_NORWEGIAN_BOKMAL 0x01 Norwegian (Bokmal)
SUBLANG_NORWEGIAN_NYNORSK 0x02 Norwegian (Nynorsk)
SUBLANG_PORTUGUESE 0x02 Portuguese
SUBLANG_PORTUGUESE_BRAZILIAN 0x01 Portuguese (Brazilian)
SUBLANG_SERBIAN_LATIN 0x02 Serbian (Latin)
SUBLANG_SERBIAN_CYRILLIC 0x03 Serbian (Cyrillic)
SUBLANG_SPANISH 0x01 Spanish (Castilian)
SUBLANG_SPANISH_MEXICAN 0x02 Spanish (Mexican)
SUBLANG_SPANISH_MODERN 0x03 Spanish (Modern)
SUBLANG_SPANISH_GUATEMALA 0x04 Spanish (Guatemala)
SUBLANG_SPANISH_COSTA_RICA 0x05 Spanish (Costa Rica)
SUBLANG_SPANISH_PANAMA 0x06 Spanish (Panama)
SUBLANG_SPANISH_DOMINICAN_REPUBLIC 0x07 Spanish (Dominican Republic)
SUBLANG_SPANISH_VENEZUELA 0x08 Spanish (Venezuela)
SUBLANG_SPANISH_COLOMBIA 0x09 Spanish (Colombia)
SUBLANG_SPANISH_PERU 0x0a Spanish (Peru)
SUBLANG_SPANISH_ARGENTINA 0x0b Spanish (Argentina)
SUBLANG_SPANISH_ECUADOR 0x0c Spanish (Ecuador)
SUBLANG_SPANISH_CHILE 0x0d Spanish (Chile)
SUBLANG_SPANISH_URUGUAY 0x0e Spanish (Uruguay)
SUBLANG_SPANISH_PARAGUAY 0x0f Spanish (Paraguay)
SUBLANG_SPANISH_BOLIVIA 0x10 Spanish (Bolivia)
SUBLANG_SPANISH_EL_SALVADOR 0x11 Spanish (El Salvador)
SUBLANG_SPANISH_HONDURAS 0x12 Spanish (Honduras)
SUBLANG_SPANISH_NICARAGUA 0x13 Spanish (Nicaragua)
SUBLANG_SPANISH_PUERTO_RICO 0x14 Spanish (Puerto Rico)
SUBLANG_SWEDISH 0x01 Swedish
SUBLANG_SWEDISH_FINLAND 0x02 Swedish (Finland)
Example
#define LANG_DUTCH 0x13
#define SUBLANG_DUTCH_BELGIAN 0x02
IF ( LOC_GetUserPrimaryLanguage() == LANG_DUTCH )
IF ( LOC_GetUserSubLanguage() == SUBLANG_DUTCH_BELGIAN )
? "Zeker en vast"
ELSE

Locale Functions
? "Vast en zeker"
ENDIF
ENDI
LOC_LastVersion() : Returns the file stamp of LOC functions.

Remark
Syntax
LOC_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\LOCALE.C-Mon Oct 19 15:55:22 1998" .

Log Functions
Log Functions

Log Functions
Functions Synopsis
FOCUS.FLL provides basic services to write log files, files that you want to write information to for tracing purposes. A
good example of a log is a file in which an application stores "secret" information such as user actions, choices,
decisions, mistakes, etc.
FOCUS.FLL supports up to 15 simultaneous logs. When FOCUS.FLL is unloaded from memory it ensures that all log
files still opened are closed properly. In the future FOCUS.VCX will use the capabilities of FOCUS.FLL to handle the
application log file.
You might expect the log functions to be improved in a very near future to accommodate needs like encrypting a log
file, compressing a log file, reading a log file, reducing a log file, etc., all functions that already exist in FOCUS.FLL
but which are still to be implemented with log files.
Using log file functions usually starts with the following calls :
&& Test whether we still have a log file available

IF ( LOG_FindFirstLog() != -1 )
&& Set a log file. If the file does not exist, it is automatically
&& created. If it exists, it is merely opened in SHARE mode, both
&& for read and write operations (which is a major advantage over
&& Visual FoxPro functions
nHandle = LOG_Set( "C:\MYLOG.LOG",1000000 )
&& If we got a valid handle
IF ( nHandle != -1 )
LOG_Append( nHandle,"This is a line of text" )
&& When the log file is no longer needed, you can close it
LOG_Close( nHandle )
ENDIF
ENDIF
Play around with LOG_*() functions and report what are the functions that are missing according to your needs.

Log Functions
LOG_Append() : Appends a line of text to a log file.

Syntax
LOG_Append( nLog,szLine )  lSuccess
Parameters
nLog log file handle given by LOG_Set() .
szLine line of text to be added to the log file.
Returns
lSuccess .T. indicates that the line was successfully added at the end of the log file; .F. otherwise.
Example
LOG_Close( nHandle )
ENDIF
ENDIF
LOG_Close() : Closes a log file.

Syntax
LOG_Close( nLog )  lSuccess
Parameters
nLog log file handle given by LOG_Set() . All log files are closed automatically when FOCUS.FLL is
removed from memory.
Returns
lSuccess .T. indicates that the file was successfully closed; .F. otherwise.
Example
IF ( ! LOG_Close( nHandle ) )
? "Log file cannot be closed"
ENDIF
ENDIF
ENDIF

Log Functions
LOG_FindFirstLog() : Finds the first available log handle.
Syntax
LOG_FindFirstLog()  nLog
Parameters
None.
Returns
nLog log file handle or –1 if not handle left.
Example
ENDIF
ENDIF
ENDIF
LOG_LastError() : Determines the last error that occurred

within the LOG_*() functions.
Alias
LOG_GetLastError()
Syntax
LOG_LastError()  szErrorCode
Parameters
nLog log file handle given by LOG_Set() . All log files are closed automatically when FOCUS.FLL is
removed from memory.
Returns
szErrorCode message describing the last error that occurred within the LOG_*() functions, or "The
command completed successfully" if everything was OK.
Example
nHandle = LOG_Set( "C:\MYLOG.LOG",1000000,2 )

Log Functions
? "Log file cannot be closed",LOG_LastError()
ENDIF
ENDIF
ELSE
? "Error:",LOG_LastError()
ENDIF
LOG_LastVersion() : Returns the file stamp of LOG functions.

Remark
Syntax
LOG_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\LOG.C-Mon Oct 19 15:55:22 1998" .
LOG_Set() : Sets a log file.

Syntax
LOG_Set( szFile,nMaximumLength,nStrategy )  nLog
Parameters
szFile name of the file in which the information will be logged.
nMaximumLength maximum size of the log file. This parameter is ignored for the moment.
nStrategy strategy to apply when the log file is full.
Returns
nLog log file handle or –1 if a log handle wasn't assigned. Don't use this handle with low-level
functions of FOCUS.FLL such as FIL_Open() or with functions of Visual FoxPro such as
FOPEN() . Log handles are special handles of FOCUS.FLL that have nothing to do with file
handles in general.
Example
nHandle = LOG_Set( "C:\MYLOG.LOG",1000000,2 )

Log Functions
ENDIF
ENDIF
ENDIF
LOG_Successful() : Returns the string that is used to declare

that the last operation has been successfully executed.
Syntax
LOG_Successful()  szConstant
Parameters
None.
Returns
szConstant "The command completed successfully".
Example
IF ( LOG_LastError() == LOG_Successful() )
ENDIF
ENDIF
ENDIF

LZH Functions
LZH Functions

LZH Functions
LZH_encode() : Compresses a file using the LZH algorithm.

Caution
The compression format is not compatible with PKZip, nor is it compatible with FIL_zip() and
FIL_unzip() .
Syntax
LZH_encode( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn the file to be compressed.
Returns
lSuccess .T. indicates that the file was compressed successfully; .F. otherwise.
Example
IF ( ! LZH_encode( "MYFILE.TXT","MYFILE.LZH" ) )
? "An error occurred while compressing the file"
ENDIF
LZH_decode() : Uncompresses a file using the LZH algorithm.

Caution
The compression format is not compatible with PKZip, nor is it compatible with FIL_zip() and
FIL_unzip() .
Syntax
LZH_decode( szFileIn,szFileOut )  lSuccess
Parameters
szFileIn the file to be uncompressed.
Returns
lSuccess .T. indicates that the file was uncompressed successfully; .F. otherwise.
Example
IF ( ! LZH_decode( "MYFILE.LZH","MYFILE.TXT" ) )
? "An error occurred while decompressing the file"
ENDIF

MAPI Functions
MAPI Functions

MAPI Functions
Functions Synopsis
Back to early versions of FOCUS.FLL we have created a library dedicated to MAPI services: FOCUMAPI.DLL . We
have decided to include these services in FOCUS.FLL directly.
What is Microsoft Mail ?

Mail is an electronic mail program for PC networks. It supports major desktop systems including MS-DOS systems,
OS/2 systems, Macintosh systems, the Windows environment and remote MS-DOS systems. Mail runs on every key PC
network, and integrates with Microsoft Mail for AppleTalk Networks. It also offers gateways to popular messaging
environments.
Mail can be supported in many different network configurations and topologies. Mail is Network Operating Systems
(NOS) independent and can run on single local area networks, bridged LANs, wide area networks, and on many more
corporate backbone networks. Mail itself can connect to foreign systems and can backbone through a foreign system.
By backboning systems, messages can be routed from one Mail system through a foreign mail system to another Mail
system.
YOU CAN USE MAIL AS A TRANSPORT MECHANISM.
What is MAPI ? What it is not ?

MAPI stands for Messaging Application Program Interface. It is a set of mechanisms Microsoft provides the developer
with to interface an application with MS-Mail in general.
The MS-Mail program and API fits a larger picture : Workgroup computing. Sharing information and resources with a
workgroup of connected computers provides a more efficient work environment in which to use the PC.
As stated earlier, this training session will make full use of simple MAPI which is only a subset of the powerful function
group known as MAPI. However, it might be important to draw up few lines that'll make you understand the the larger
picture I was talking about.
In addition to MAPI, Microsoft has also designed FFAPI (File Format Application Program Interface) which is a group of
programs you can make use of in order to exchange electronic mail between Microsoft Mail and other mail systems or
applications. Armed with the appropriate expertise you'll learn how to access the Mail data files from within your
application. In that sense, FFAPI is the primary layer you can make use of.
FFAPI is divided into two separate products :
 Gateway FFAPI
 Application FFAPI
Use gateway FFAPI to build a gateway to connect to Microsoft Mail with another electronic messaging system. This is
pretty advanced !
Use Application FFAPI to create a custom application that uses Microsoft Mail to transport information. With a modified
version of Application FFAPI, Application Remote FFAPI, you can also create applications for remote use.
Transport of information is the corner stone of the larger picture. Because it is not limited to messages in general but
rather opened to all types of data (order forms, objects, etc.) it can be used in a wide variety of situations where
communication between two or more workstations is exactly what is required. Getting acquainted with the Mail
transport layer simply opens your applications to a broad set of professional features.
THIS PART OF THE DOCUMENTATION MUST BE CONTINUED. MAPI FUNCTIONS ARE NOT YET OPERATIONAL

MAPI Functions
The Messaging Application Program Interface for C programmers
The simple messaging application program interface is a set of C functions that helps you create mail-enabled
applications.
With simple MAPI you can easily add messaging to any Windows application. Some MAPI functions include a user
interface (a dialog box), but you can also call MAPI functions without generating user interface concerns.
Simple MAPI Functions

Simple MAPI consists of the following functions :
Function Description
MAPILogon Begins a session with the messaging system.
MAPIFindNext Returns the ID of the next (or first) mail message of a specified type.
MAPIReadMail Reads a mail message.
MAPISaveMail Saves a mail message.
MAPIDeleteMail Deletes a mail message.
MAPISendMail Sends a mail message, allowing greater flexibility than
MAPISendDocuments in message generation.
MAPISendDocuments Sends a standard mail message using a dialog box.
MAPIAddress Addresses a mail message.
MAPIResolveName Displays a dialog box to resolve an ambiguous recipent name.
MAPIDetails Displays a recipient details dialog box.
MAPIFreeBuffer Frees memory allocated by the messaging system.
MAPILogoff Ends a session with the messaging system.
Simple MAPI structures

Message information is stored in MAPI structures :
Structure Description
MapiFileDesc Contains file attachment information.
MapiMessage Contains message information.
MapiRecipDesc Contains recipient information.
MapiFileDesc
typedef struct {
ULONG ulReserved ; // Reserved for future use. Must be 0
ULONG flFlags ; // Flags
ULONG nPosition ; // Attachment position in message body
LPSTR lpszPathName ; // Full path name of attached file
LPSTR lpszFileName ; // Original filename (optional)
LPVOID lpFileType ; // Attachment file type (reserved)
} MapiFileDesc, *lpMapiFileDesc;
MapiMessage
typedef struct {
ULONG ulReserved ; // Reserved for future use. Must be 0
LPSTR lpszSubject ; // Message subject
LPSTR lpszNoteText ; // Message text
LPSTR lpszMessage Type ; // Message class
LPSTR lpszDateReceived ; // In YYYY/MM/DD HH:MM format
LPSTR lpszConversationID ; // Conversation tread ID
ULONG flFlags ; // Unread, return receipt
lpMapiRecipDesc lpOriginator; // Originator descriptor
ULONG nRecipCount ; // Number of recipients
lpMapiRecipDesc lpRecips ; // Recipient descriptors
ULONG nFileCount ; // Number of file attachments
lpMapiFileDesc lpFiles ; // Attachment descriptors
} MapiMessage, *lpMapiMessage;

MAPI Functions
MapiRecipDesc
typedef struct {
ULONG ulReserved ; // Reserved for future use.
ULONG ulRecipClass ; // Recipient class
LPSTR lpszName ; // Recipient name
LPSTR lpszAddress ; // Recipient address
ULONG ulEIDSize ; // Size in bytes of lpEntryID
LPVOID lpEntryID ; // System-specific recipient reference
} MapiMessage, *lpMapiMessage;
Even if it is not really important to know all these functions and structures in a very detailed manner, it gives you a
good insight of what's possible and what's not.
Simple MAPI C Functions insight

To determine whether MAPI is available at run time, check for the MAPI variable in the [Mail] section of WIN.INI. If
this variable is present and nonzero, it indicates that a MAPI.DLL library is available. If the MAPI variable is not
present or is 0, then you cannot call the MAPI functions, and you should not enable applications for mail.
Although very simple in its principle, this strategy imposes to be able to read *.INI files and to rely on the user
maturity (having a mail section in the WIN.INI file does not imply that the MAPI.DLL file is physically present on the
workstation : this file might have been deleted or removed to a non appropriate place). You'll see later how we came
to an acceptable solution to this problem.
Because we want to step logically into MAPI, we won't go along the usual alphabetical order. Therefore, before actually
wondering whether MAPI is available or not, we'll consider that MAPI is properly installed, up and ... not running.
Logon/logoff process
It is pretty straightforward that we'll have to deal with MAPILogon and MAPILogoff services in order to start and stop a
Mail session.
Logon
MAPILogon() begins a session with the messaging system. You can sign in to the messaging system in 2 ways :
 Implicitly sign in
 Explicitely sign in
Implicit log on
Any MAPI function call made outside of an established MAPI session generates a sign-in dialog box. We won't cover
these techniques.
Explicit log on
If you want to maintain a session over a number of simple MAPI calls, you can use the MAPILogon() function to
provide a session handle to the messaging system. This handle can be used in subsequent MAPI calls to explicitly
provide user credentials to the messaging system.
The code of such a function is coming up (However it is not our definite code yet) :
MAPILogon() prototype
ULONG MAPILogon( ULONG ulUIParam , // Parent window handle
LPSTR lpszName , // Client account-name string
LPSTR lpszPassword, // Credential string
ULONG flFlags , // Flags to start the session with
ULONG ulReserved , // Reserved for future use
LHANDLE *lphSession ) // Pointer to a session handle

MAPI Functions
MAPILogon() return
Manifest constant Value Description

MAPI_E_FAILURE 2 One or more unspecified errors occurred during sign-in.
MAPI_E_INSUFFICIENT_MEMORY 5 Not enough memory to proceed.
MAPI_E_LOGIN_FAILURE 3 No default sign-in and the user failed to sign-in successfully.
MAPI_E_TOO_MANY_SESSIONS 8 Too many sessions open simultenously.
MAPI_E_USER_ABORT 1 The user cancelled the process.
SUCCESS_SUCCESS 0 OK. Pointer to session handle set successfully.
C code to interface with FoxPro

FOCUSFNC FW_MAI_logon( XBASE_PARAMETERS )
/*-------------------------------------*/
{
FLAGS flFlags = MAPI_LOGON_UI; // Display dialog if required
char _far *Name = NULL; // NULL by default
char _far *PassWord = NULL; // NULL by default
short nParam = PCOUNT(); // n parameters
AccessDenied = FALSE; // Access = OK
switch ( nParam ) // How many parameters ?

{
case 2:_initparc(2);
PassWord = _parc(2); // User password
case 1:_initparc(1);
Name = _parc(1); // User name
}
if ( MAILForceDownLoad ) // Should we force a download ?

flFlags |= MAPI_FORCE_DOWNLOAD;
_retni( (long ) MAPILogon( FOXWINDOW() , // Returns session handle

Name ,
PassWord ,
flFlags ,
0L ,
&hMAPISession
)
);
switch ( nParam ) // How many parameters ?

{
case 2:_deinitparc(2); // Free handle 1
case 1:_deinitparc(1); // Free handle 2
}
return 0; // Return an int

}
That's it ! Now, we have to be able to log off.
Logoff
MAPILogoff() prototype
ULONG MAPILogoff( LHANDLE lphSession, // Session handle
ULONG ulUIParam , // Parent window handle
ULONG flFlags , // Reserved for future use. Must be 0
ULONG ulReserved ) // Reserved for future use. Must be 0
MAPILogoff() returns

MAPI_E_INVALID_SESSION 19 An invalid session handle was used for the lhSession parameter.
SUCCESS_SUCCESS 0 OK.

MAPI Functions
FOCUSFNC FW_MAI_logoff()
/*--------------------*/
{
_retni( (long) MAPILogoff( hMAPISession,
FOXWINDOW() ,
0L ,
0L
)
);
return 0;
}
At this point we can already start a session, and later on, cancel this session any time from within the FoxPro code. It
is not exactly all we want to be able to do, but it's a good start. Let's now focus on messages that are going to be sent
across the mail system.
Sending a message : MAPISendMail()

ULONG MAPISendMail( LHANDLE lhSession , // Session handle
lpMapiMessage lpMessage, // Pointer to MapiMessage structure
ULONG flFlags , // Reserved for future use. Must be 0
This function sends a standard mail message. It can prompt for user input with a dialog box or proceed without any
user interaction.
MAPISendMail() returns

MAPI_E_AMBIGUOUS_RECIP 21 A recipient matched more than one of the recipient descriptor
structures.
MAPI_E_ATTACHMENT_NOT_FOUND 11 The specified attachment was not found.
MAPI_E_BAD_RECIPTYPE 15 Invalid recipient type.
MAPI_E_DISK_FULL 4 Disk was full.
MAPI_E_FAILURE 2 One or more unspecified errors occurred while sending the mail.
MAPI_E_TEXT_TOO_LARGE 18 The text in the message was too large to be sent.
MAPI_E_TOO_MANY_FILES 9 There were too many file attachments.
MAPI_E_TOO_MANY_RECIPIENTS 10 There were too many recipients specified.
MAPI_E_TOO_MANY_SESSIONS 8 The user had too many sessions open at once.
MAPI_E_UNKNOWN_RECIPIENT 14 The recipient did not appera in the address list.
MAPI_E_USER_ABORT 1 The user cancelled the process from the dialog box.

FOCUSFNC FW_MAI_send()
/*------------------*/
{
FLAGS flFlags = MAPI_DIALOG;
_retni( (long) MAPISendMail( hMAPISession ,

0 ,
&mmMapiMessage,
flFlags ,
0L
)
);
return 0;
}

MAPI Functions
Sending a document : MAPISendDocuments()
ULONG MAPISendDocuments( ULONG ulUIParam , // Parent window handle
LPSTR lpszDelimChar, // Character pointer delimit names
LPSTR lpszFilePaths, // Ptr to list of full paths
LPSTR lpszFileNames, // Ptr to a list of original filenames
This function sends a standard mail message using a dialog box. It displays a Send Note dialog box which prompts the
user to send a mail message with data file attachments.
MAPISendDocuments() returns
MAPI_E_ATTACHMENT_OPEN_FAILURE 12 One or more files in the lpszFilePaths parameter could not be
located.
MAPI_E_FAILURE 2 One or more unspecified errors occurred while sending the mail.
MAPI_E_USER_ABORT 1 The user cancelled the process from the dialog box.

FOCUSFNC FW_MAI_sendoc( XBASE_PARAMETERS )
/*--------------------------------------*/
{
ULONG ulResult;
char _far *Source;

char _far *Target;
_initparc(1); _initparc(2);
Source = _parc(1); Target = _parc(2);
ulResult = (ULONG) MAPISendDocuments( 0,";",Source,Target,0L );
_deinitparc(1); _deinitparc(2);
_retni( (int) ulResult );

return 0;
}
Reading a message : MAPIReadMail()

This is the ideal function to demonstrate that we'll have to create our own .FLL in order to interface with MAPI. Why is
that ? Because you cannot return C structures to FoxPro. This is due to the fact that the FoxPro arsenal does not
contain such data constructions. Therefore, we'll have to temporarily store the information in C and use subsequent
function calls to retrieve all the message information.
ULONG MAPIReadMail( LHANDLE lhSession , // Opaque session handle
LPSTR lpszMessageID, // Ptr to the message identifier
ULONG flFlags , // Bitmask of flags
ULONG ulReserved , // Reserved for future use. Must be 0
lpMapiMessage *lppMessage ) // Ptr to a message structure
MAPIReadMail() returns
MAPI_E_ATTACHMENT_WRITE_FAILURE 13 An attachment could not be written to a temporary file.
MAPI_E_FAILURE 2 One or more unspecified errors occurred while reading the mail.
MAPI_E_INVALID_MESSAGE 3 The message ID was invalid.
MAPI_E_NOT_SUPPORTED 26 The operation was not supported by the messaging system.
MAPI_E_TOO_MANY_FILES 9 There were too many file attachments.
MAPI_E_TOO_MANY_RECIPIENTS 10 There were too many recipients specified.

MAPI Functions
FOCUSFNC FW_MAI_read( XBASE_PARAMETERS )
/*------------------------------------*/
{
long nResult = -1;
FLAGS flFlags = MAPI_SUPPRESS_ATTACH; // Display dialog if required
if ( ! MAILShouldMark )
flFlags |= MAPI_PEEK;
if ( MsgAvailable )
{
lppMessage = (lpMapiMessage FAR *) &lpMessage; // Pointer to structure
nResult = (long ) MAPIReadMail( hMAPISession ,
FOXWINDOW() ,
lpszMessageID ,
flFlags ,
0L ,
lppMessage
);
if ( nResult != SUCCESS_SUCCESS )
goto Failure;
cFWFrom[0] = cFWDate[0] = cFWSubject[0] = 0;
if ( cFWText == NULL )
cFWText = _xgrab( 4097,&mhcFWText );
_MemFill( (void FAR *) cFWText,0,4096 );
if ( lpMessage->lpOriginator->lpszName != NULL )
_fstrncat( (LPSTR) cFWFrom,lpMessage->lpOriginator->lpszName,40 );
if ( lpMessage->lpszDateReceived )
_fstrncat( (LPSTR) cFWDate,lpMessage->lpszDateReceived ,40 );
if ( lpMessage->lpszSubject != NULL )
_fstrncat( (LPSTR) cFWSubject,lpMessage->lpszSubject ,100 );
if ( lpMessage->lpszNoteText != NULL )
_fstrncat( (LPSTR) cFWText,lpMessage->lpszNoteText ,4095 );
MAPIFreeBuffer( (LPVOID) lpMessage );

}
Failure:
_retni( nResult );
return 0;
}
As you can see, the MAI_read() function only retrieves message information from the C structures and store it to
temporary buffers. Later on, thanks to additional services we'll have to construct, we will definitely be able to pass the
informations to FoxPro.
Additional services
You can only call these services when a prior call to MAI_read() returned SUCCESS_SUCCESS.
Message originator : MAI_from()

FOCUSFNC FW_MAI_from()
/*------------------*/
{
_retc( cFWFrom[0] == 0 ? "" : cFWFrom );
return 0;
}
Message date : MAI_date()

FOCUSFNC FW_MAI_date()
/*------------------*/
{
_retc( cFWDate[0] == 0 ? "" : cFWDate );
return 0;
}

MAPI Functions
Message subject : MAI_subjec()
FOCUSFNC FW_MAI_subjec()
/*--------------------*/
{
_retc( cFWSubject[0] == 0 ? "" : cFWSubject );
return 0;
}
Message body (text) : MAI_text()

FOCUSFNC FW_MAI_text()
/*------------------*/
{
if ( cFWText != NULL )
_retc( *cFWText == 0 ? "" : cFWText );
else
_retc( "" );
return 0;
}
Next message : MAPIFindNext()

This function allows an application to enumerate messages of a given type. It returns message identifiers that can be
used in subsequent MAPI function calls to retrieve and delete messages. MAPIFindNext() is for processing incoming
mail, not for managing received mail. MAPIFindNext() looks for messages in the folder in which new messages of the
specified type are delivered.
ULONG MAPIReadMail( LHANDLE lhSession , // Opaque session handle
LPSTR lpszMessageType , // Ptr to the message identifier
LPSTR lpszSeedMessageID, // Ptr to a string that is the seed
ULONG flFlags , // Bitmask of flags
ULONG ulReserved , // Reserved for future use. Must be 0
LPSTR lpszMessageID ) // Ptr to a caller-allocated string
MAPIFindNext() returns
MAPI_E_FAILURE 2 One or more unspecified errors occurred while looking for messages.
MAPI_E_INVALID_MESSAGE 17 The message ID of lpszSeedMessageID was invalid.
MAPI_E_NO_MESSAGES 16 MAPIFindNext couldn't find a matching message
MAPI_E_USER_ABORT 1 The user cancelled the process.

FOCUSFNC FW_MAI_next()
/*------------------*/
{
ULONG ulResult;
FLAGS flFlags;
if ( iFindFirst )
{
*lpszSeedMessageID = '\0';
iFindFirst = FALSE;
}
else
_fstrcpy( lpszSeedMessageID,lpszMessageID );
if ( MAILUnReadOnly )
flFlags = MAPI_UNREAD_ONLY;
else
flFlags = 0L;
ulResult = (*lpfnMAPIFindNext)( hMAPISession ,

FOXWINDOW() ,
NULL ,
lpszSeedMessageID,
flFlags ,
MAPI Functions
0L ,
lpszMessageID );
if ( ulResult != SUCCESS_SUCCESS )
MsgAvailable = FALSE;
else
MsgAvailable = TRUE;
_retni( (long) ulResult );
return 0;
}
Building a kind of "MAPI .FLL" for FoxPro

The main problem we'll have to deal with is to load the MAPI dynamic link libraries and to solve all related issues. This
actually includes library loading but also function registration (pointers to functions).
Loading the MAPI libraries

#define FOXWINDOW() (ULONG) _WhToHwnd( _WMainWindow() )
HANDLE hMAPILibrary;
HANDLE hSCHEDULELibrary;
LHANDLE hMAPISession;
LHANDLE hSPLUSSession;
int MAILAvailable = FALSE; // Is MAPI installed ?

int SCHEDULEAvailable = FALSE; // Is schedule+ available ?
int InScheduleSession = FALSE; // Are we in a Schedule+ session ?
// Function prototypes
FOCUSFNC InitMAIL( void );
FOCUSFNC DeInitMAIL( void );
FOCUSFNC MAPIStarting()
/*-------------------*/
{
InitMAIL();
return 0;
}
FOCUSFNC MAPIEnding()
/*-----------------*/
{
DeInitMAIL();
return 0;
}
FOCUSFNC FW_MAI_ismapi()
/*--------------------*/
{
_retl( MAILAvailable );
return 0;
}
FOCUSFNC FW_SCH_issche()
/*--------------------*/
{
_retl( SCHEDULEAvailable );
return 0;
}
void InitMessage( lpMapiMessage pmmMessage )

/*-----------------------------------------*/
{
pmmMessage->ulReserved = 0L;
pmmMessage->lpszSubject = pszSubject;
pmmMessage->lpszNoteText = pszNoteText;
pmmMessage->lpszMessageType = NULL;
pmmMessage->lpszDateReceived = pszDateReceived;
pmmMessage->flFlags = MAPI_UNREAD;
pmmMessage->lpOriginator = &rdOriginator;
pmmMessage->nRecipCount = 0L;
pmmMessage->lpRecips = NULL;
pmmMessage->nFileCount = 0L;
pmmMessage->lpFiles = NULL;
}
FOCUSFNC InitMAIL()

MAPI Functions
/*---------------*/
{
// Microsoft Windows does not have to handle errors !
unsigned int OldErrorMode = SetErrorMode( SEM_FAILCRITICALERRORS | SEM_NOOPENFILEERRORBOX );
iFindFirst = TRUE;
MAILAvailable = FALSE;
SCHEDULEAvailable = FALSE;
szSeedMessageID[0] = 0;
szMessageID[0] = 0;
szSubject[0] = 0;
szNoteText[0] = 0;
InitMessage( &mmMapiMessage );
hMAPILibrary = LoadLibrary( "MAPI.DLL" );

hSCHEDULELibrary = LoadLibrary( "SPLUS.DLL" );
SetErrorMode( OldErrorMode ); // Setup error mode at what it was prior to enter this function
if ( hMAPILibrary < HINSTANCE_ERROR )

return( (int) hMAPILibrary );
MAILAvailable = TRUE;
// Loading MAPI functions. If an error occurs loading one of these functions, there is no need for us to make MAPI
// available. Since Schedule+ heavily relies on MAPI, by making MAPI not available, we'll also make Schedule+ not
// available !
if (((FARPROC) lpfnMAPILogon = GetProcAddress( hMAPILibrary,"MAPILogon" )) == NULL )

RETURN_MAPI_ERROR();
if (((FARPROC) lpfnMAPILogoff = GetProcAddress( hMAPILibrary,"MAPILogoff" )) == NULL )

if (((FARPROC) lpfnMAPISendMail = GetProcAddress( hMAPILibrary,"MAPISendMail" )) == NULL )

if (((FARPROC) lpfnMAPISendDocuments = GetProcAddress( hMAPILibrary,"MAPISendDocuments" )) == NULL )

if (((FARPROC) lpfnMAPIFindNext = GetProcAddress( hMAPILibrary,"MAPIFindNext" )) == NULL )

if (((FARPROC) lpfnMAPIReadMail = GetProcAddress( hMAPILibrary,"MAPIReadMail" )) == NULL )

if (((FARPROC) lpfnMAPISaveMail = GetProcAddress( hMAPILibrary,"MAPISaveMail" )) == NULL )

if (((FARPROC) lpfnMAPIDeleteMail = GetProcAddress( hMAPILibrary,"MAPIDeleteMail" )) == NULL )

if (((FARPROC) lpfnMAPIFreeBuffer = GetProcAddress( hMAPILibrary,"MAPIFreeBuffer" )) == NULL )

if (((FARPROC) lpfnMAPIAddress = GetProcAddress( hMAPILibrary,"MAPIAddress" )) == NULL )

if (((FARPROC) lpfnMAPIDetails = GetProcAddress( hMAPILibrary,"MAPIDetails" )) == NULL )

if (((FARPROC) lpfnMAPIResolveName = GetProcAddress( hMAPILibrary,"MAPIResolveName" )) == NULL )

// Loading Schedule+ ! If we came around here, it means that everything was OK. Now, we'll have to check
// out whether Schedule+ can load properly.
SCHEDULEAvailable = ! ( hSCHEDULELibrary < HINSTANCE_ERROR );
if (((FARPROC) lpfnSPLUSBeginSession = GetProcAddress( hSCHEDULELibrary,"SPLUSBeginSession" )) == NULL )

RETURN_SCHEDULE_ERROR();
if (((FARPROC) lpfnSPLUSEndSession = GetProcAddress( hSCHEDULELibrary,"SPLUSEndSession" )) == NULL )

if (((FARPROC) lpfnSPLUSSaveAppt = GetProcAddress( hSCHEDULELibrary,"SPLUSSaveAppt" )) == NULL )

if (((FARPROC) lpfnSPLUSSaveTask = GetProcAddress( hSCHEDULELibrary,"SPLUSSaveTask" )) == NULL )

if (((FARPROC) lpfnSPLUSSendMeeting = GetProcAddress( hSCHEDULELibrary,"SPLUSSendMeeting" )) == NULL )

if (((FARPROC) lpfnSPLUSReadUserInfo = GetProcAddress( hSCHEDULELibrary,"SPLUSReadUserInfo" )) == NULL )


MAPI Functions
}
FOCUSFNC DeInitMAIL()
/*-----------------*/
{
// Seek first message
iFindFirst = TRUE;
// Free MAPI.DLL
if ( MAILAvailable )
FreeLibrary( hMAPILibrary );
// Free memory allocated to cFWText

if ( cFWText != NULL )
_xfree( mhcFWText );
// Free SPLUS.DLL
if ( SCHEDULEAvailable )
FreeLibrary( hSCHEDULELibrary );
// NULL pointers
lpfnMAPILogon = NULL;
lpfnMAPILogoff = NULL;
lpfnMAPISendMail = NULL;
lpfnMAPISendDocuments = NULL;
lpfnMAPIFindNext = NULL;
lpfnMAPIReadMail = NULL;
lpfnMAPISaveMail = NULL;
lpfnMAPIDeleteMail = NULL;
lpfnMAPIFreeBuffer = NULL;
lpfnMAPIAddress = NULL;
lpfnMAPIDetails = NULL;
lpfnMAPIResolveName = NULL;
return(0);
}
Determining whether MAPI is available or not

Remember what Microsoft was recommending ?
To determine whether MAPI is available at run time, check for the MAPI variable in the [Mail] section of WIN.INI. If
this variable is present and nonzero, it indicates that a MAPI.DLL library is available. If the MAPI variable is not present
or is 0, then you cannot call the MAPI functions, and you should not enable applications for mail.
I agree saying that Mail system will only run if [MAIL] section exists in the WIN.INI file and if the MAPI variable is
nonzero. But the problem is that, even if the WIN.INI file contains such a section and even if the variable is nonzero,
that does not automatically imply that the Mail system is really enabled ... for the same reasons we were referring to
earlier. So that I suggest to use a mixture of two strategies :
1. Check for the existence of the [MAIL] section. Check for the presence of the MAPI variable (nonzero).
1. Load appropriate DLLs. If those do not load properly, then MAPI is not available !
The code described above tries to load MAPI.DLL. Here is an extract of this code :
hMAPILibrary = LoadLibrary( "MAPI.DLL" );
if ( hMAPILibrary < HINSTANCE_ERROR )

MAILAvailable = TRUE;
But how can we search the WIN.INI file for the [MAIL] section ? Because this is not a built-in feature of FoxPro, we
once again have to turn to C to build our own service (which is only a call to a Windows SDK service).
Checking [MAIL] section

FOCUSFNC FW_FIL_wreain( XBASE_PARAMETERS )
/*--------------------------------------*/
{
char _far *Section,*Entry;

MAPI Functions
char szBuf[133];
_initparc(1); _initparc(2);
Section = _parc(1); // Handle to pointer : 1st param

Entry = _parc(2); // Handle to pointer : 2nd param
GetProfileString( Section,Entry,"",szBuf,sizeof(szBuf) );
_retc( szBuf );
_deinitparc(1); _deinitparc(2);
return 0;
}
Example :
PRIVATE cMAPI
cMAPI = FIL_wreain( "Mail","MAPI" )
IF ( EMPTY( cMAPI ) )
=StopDialog( "MAPI is not available" )
ELSE
IF ( VAL( cMapi ) == 0 )
ELSE
=InfoDialog( "MAPI should be there..." )
<... now let's try to load MAPI>
ENDIF
ENDIF
Having said this, you'll have now to load the library we are about to create. Imagine our own FLL is called
FOCUMAPI.FLL, then most likely you'll have to come up with the following code :
PUBLIC m.lIsMapi
PRIVATE m.cMAPI
m.lIsMapi = .F.
m.cMAPI = FIL_wreain( "Mail","MAPI" )
IF ( EMPTY( m.cMAPI ) )
ELSE
IF ( VAL( m.cMapi ) == 0 )
ELSE
SET LIBRARY TO FOCUMAPI.FLL ADDITIVE
IF ( ! MAI_ismapi() )
RELEASE LIBRARY FOCUMAPI.FLL
ELSE
m.lIsMapi = .T.
ENDIF
ENDIF
ENDIF
Then, along all your application code, simply check for the m.lIsMapi variable to allow MAPI calls or not.
<END OF DOCUMENTATION CHECK>

MAPI Functions
MAPI_IsMAPI() : Determines whether MAPI is installed.

Syntax
MAPI_IsMAPI()  lMAPI
Parameters
None.
Returns
lMAPI .T. if MAPI is installed; .F. if not.

MCI Functions
MCI Functions

MCI Functions
MCI_device() : Retrieves the device identifier corresponding to

the name of an open device.
Syntax
MCI_device( szDevice )  nDevice
Parameters
szDevice device name or the alias name by which the device is known.
Returns
nDevice device identifier assigned to the device when it was opened if successful. The identifier is used
in the mciSendCommand() function. If the device name is not known, if the device is not
open, or if there was not enough memory to complete the operation, the return value is zero.
MCI_error() : Gets last MCI command error string.

Alias
MCI_LastError(), MCI_GetlastError()
Comment
When calling this function the last MCI error is cleared off.
Syntax
MCI_error()  szMCIError
Parameters
None.
Returns
szMCIError error string.
MCI_IsRiff() : Is a given file in the RIFF format?

Syntax
MCI_IsRiff( szFile )  lRiff
Parameters
Returns
lRiff .T. if RIFF format; .F. otherwise.

MCI Functions
MCI_IsWave() : Is a given file in the WAVE format?
Syntax
MCI_IsWave( szFile )  lWave
Parameters
Returns
lWave .T. if WAVE format; .F. otherwise.
MCI_LastVersion() : Returns the file stamp of MCI functions.

Remark
Syntax
MCI_LastVersion()  szLastVersion
Parameters
None.
Returns
MCI_send() : Sends a command to MCI devices.

Special
You should take a look at multimedia commands in order to use this function.
Syntax
MCI_send( szCommand )  szDescription
Parameters
szCommand command to be executed by MCI devices.
Returns
szDescription textual description of MCI command execution.

Metric Functions
Metric Functions

Metric Functions
MET_CmToInch() : Cm to inches.
Remark
The precision of the function is not acceptable for scientific computations.
Syntax
MET_CmToInch( nCm )  nInches
Parameters
nCm centimeters.
Returns
nInches inches.
MET_FeetToInch() : Feet to inches.

Remark
Syntax
MET_FeetToInch( nFeet )  nInches
Parameters
nFeet feet.
Returns
nInches inches.
MET_FeetToMeters() : Feet to meters.

Remark
Syntax
MET_FeetToMeters( nFeet )  nMeters
Parameters
nFeet feet.
Returns
nMeters meters.
Example
? "Brad Pitt is " + ALLTRIM( STR( MET_FeetToMeters(6) * 100 ) ) + " cm tall"
? "Brad Pitt is " + ALLTRIM( STR( MET_MetersToFeet(1.83),20,2 ) ) + " feet tall"

Metric Functions
MET_FeetToMile() : Feet to miles.
Remark
Syntax
MET_FeetToMile( nFeet )  nMiles
Parameters
nFeet feet.
Returns
nMiles miles.
MET_FeetToYard() : Feet to yards.

Remark
Syntax
MET_FeetToYard( nFeet )  nYards
Parameters
nFeet feet.
Returns
nYards yards.
MET_InchToCm() : Inches to cm.

Remark
Syntax
MET_InchToCm( nInches )  nCm
Parameters
nInches inches.
Returns
nCm centimeters.

Metric Functions
MET_InchToFeet() : Inches to feet.
Remark
Syntax
MET_InchToFeet( nInches )  nFeet
Parameters
nInches inches.
Returns
nFeet feet.
MET_InchToMile() : Inches to miles.

Remark
Syntax
MET_InchToMile( nInches )  nMiles
Parameters
nInches inches.
Returns
nMiles miles.
MET_InchToYard() : Inches to yards.

Remark
Syntax
MET_InchToYard( nInches )  nYards
Parameters
nInches inches.
Returns
nYards yards.

Metric Functions
MET_KmToMile() : Km to mile.
Remark
Syntax
MET_KmToMile( nKm )  nMiles
Parameters
nKm kilometers.
Returns
nMiles miles.
MET_LastVersion() : Returns the file stamp of MET functions.

Remark
Remark
Syntax
MET_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\METRIC.C-Mon Oct 19 15:55:22 1998" .
MET_MetersToFeet() : Meters to feet.

Remark
Syntax
MET_MetersToFeet( nMeters )  nFeet
Parameters
nMeters meters.

Metric Functions
Returns
nFeet feet.
Example
? "Brad Pitt is " + ALLTRIM( STR( MET_FeetToMeters(6) * 100 ) ) + " cm tall"
? "Brad Pitt is " + ALLTRIM( STR( MET_MetersToFeet(1.83),20,2 ) ) + " feet tall"
MET_MileToKm() : Miles to km.

Remark
Syntax
MET_MileToKm( nMiles )  nKm
Parameters
nMiles miles.
Returns
nKm kilometers.
MET_MileToFeet() : Miles to feet.

Remark
Syntax
MET_MileToFeet( nMiles )  nFeet
Parameters
nMiles miles.
Returns
nFeet feet.
MET_MileToInch() : Miles to inches.

Remark
Syntax
MET_MileToInch( nMiles )  nInches
Parameters
nMiles miles.

Metric Functions
Returns
nInches inches.
MET_MileToYard() : Miles to yards.

Remark
Syntax
MET_MileToYard( nMiles )  nYards
Parameters
nMiles miles.
Returns
nYards yards.
MET_MToYard() : Meters to yards.

Remark
Syntax
MET_MToYard( nM )  nYards
Parameters
nM meters.
Returns
nYards yards.
MET_YardToFeet() : Yards to feet.

Remark
Syntax
MET_YardToFeet( nYards )  nFeet
Parameters
nYards yards.
Returns
nFeet feet.

Metric Functions
MET_YardToInch() : Yards to inches.
Remark
Syntax
MET_YardToInch( nYards )  nInches
Parameters
nYards yards.
Returns
nInches inches.
MET_YardToM() : Yards to meters.

Remark
Syntax
MET_YardToM( nYards )  nM
Parameters
nYards yards.
Returns
nM meters.
MET_YardToMile() : Yards to mile.

Remark
Syntax
MET_MileToYard( nYards )  nMiles
Parameters
nYards yards.
Returns
nMiles miles.

Miscellaneous Functions

MIS_Aliases() : Returns all the aliases that are known for a

specified FOCUS.FLL function.
Syntax
MIS_Aliases( szFunction )  szAliases
Parameters
the function name.
Returns
szAliases a string with all known aliases of a given function. Each alias is semi-colon separated from the
other. The return value is an empty string is the function is not found. The function name is also
listed in the aliases of the function.
Example
? MIS_Aliases( "MIS_Vers" ) && "MIS_VER;MIS_VERS;MIS_VERSION"
MIS_AllFunctions() : Returns all the function and aliases that

are known in FOCUS.FLL.
Syntax
MIS_AllFunctions()  szFuncs
Parameters
None.
Returns
szFuncs a string with all functions and aliases contained in FOCUS.FLL . The element of the list is
separated from the other by a semicolon (";" ).
Example
LOCAL OldSep
&& Saving current separator list

OldSep = STR_setsep( ";" )
IF ( STR_numtok( MIS_AllFunctions() ) != MIS_NumberOfFunctions() )

? "Who is right now? The number of functions seems to be incorrect"
ENDIF
&& Resetting separators to what they were

STR_setsep( OldSep )
&& The following example lists all functions starting with "STR" (all string functions)
Filter( "STR" )
FUNCTION Filter( szPrefix )
LOCAL szAllFunctions
LOCAL nFunctions
LOCAL nArgs
LOCAL i
LOCAL OldSep

nArgs = PCOUNT()
IF ( nArgs == 0 )
cPrefix = "*"
ELSE
cPrefix = cPrefix + "_*"
ENDIF
SET LIBRARY TO "focus.fll"
szAllFunctions = MIS_AllFunctions()
nFunctions = MIS_NumberOfFunctions()
FOR i = 1 TO nFunctions
szFunction = STR_ntoken( i,szAllFunctions )
IF ( LIKE( szPrefix,szFunction ) )
? cFunction
ENDIF
NEXT
SET LIBRARY TO
RETURN ( .NULL. )
MIS_Argc() : Number of arguments that a specified function of

FOCUS.FLL expects.
Syntax
MIS_Argc( szFunction )  nParams
Parameters
szFunction function to look for in FOCUS.FLL .
Returns
nParams number of parameters or –1 if the function is not found.
Example
? MIS_Argc( "MIS_IsFunction" ) && 1
MIS_Argv() : Argument types that a specified function of

FOCUS.FLL expects.
Alias
DDA_Argv(), MIS_PList(), DDA_Parameters(), DDA_Params(), DDA_ParamTypes(), DDA_PList()
Syntax
MIS_Argv( szFunction )  szParamTypes
Parameters
szFunction function to look for in FOCUS.FLL .
Returns
szParamTypes parameters types or an empty string is the function is not found. If the specified function does
not expect any parameter, MIS_Argv() also returns an empty string.

"" No parameter
"0" .NULL.
"?" Any type can be passed
"C" Character type
"D" Date type
"I" Integer type
"L" Logical type
"N" Numeric type
"R" Reference
"T" Datetime type
"Y" Currency type
Example
? MIS_Argv( "MIS_False" ) && ".?,.?,.?,.?,.?,.?,.?,.?,.?,.?"
MIS_BodyMassIndex() : Calculates the body mass index.

Syntax
MIS_BodyMassIndex( nWeight,nHeight )  nIndex
Parameters
nWeight weight in kilos.
nHeight height in centimeters.
Returns
nIndex A good body mass index should be comprised between 20 and 25.
MIS_credits() : Returns the credits of FOCUS.FLL.

Syntax
MIS_credits()  szCredits
Parameters
None.
Returns
szCredits credits.
Example
? MIS_credits() && " FOCUS code by Pat Boens & Anurak Kongthong, FOCUS doc by Pat Boens & Pete
Cuiry, FOCUS Online doc by Pat Boens and Korakot Leelachareanwaranon"
See also
MIS_major() , MIS_minor() , MIS_knlmajor() , MIS_knlminor() , MIS_DocVers() ,
MIS_OnlineDocVers() , MIS_vers()

MIS_DocVers() : Returns the version of the FOCUS
documentation.
Alias
MIS_DocVer(), MIS_DocVersion()
Syntax
MIS_DocVers()  szDocVers
Parameters
None.
Returns
szDocVers Documentation version.
Example
? MIS_DocVers() && "FOCUS documentation by Pat Boens & Pete Cuiry - Tue Apr 20 21:37:38 1999-v
6.03"
See also
MIS_major() , MIS_minor() , MIS_knlmajor() , MIS_knlminor() , MIS_Credits() ,
MIS_OnlineDocVers() , MIS_vers()
MIS_Error() : Generates a Visual FoxPro error.

Caution
Don't use this function so far because it generates unexpected error codes.
Syntax
MIS_Error( nError )  .T.
Parameters
nError specifies the number of the error to generate.
Returns
See also
MIS_UserError(), MIS_ErrorInfo()
MIS_ErrorInfo() : Visual FoxPro error message associated with

the error.
Caution
Don't use this function so far because it generates unexpected error messages.

Syntax
MIS_ErrorInfo( nError )  szErrorMsg
Parameters
nError specifies the number of the error to obtain information about.
Returns
szErrorMsg error message corresponding to the nError .
See also
MIS_UserError(), MIS_Error()
MIS_ExecFuncPtr() : Executes the code that is pointed to by

the internal execution pointer.
Alias
DDA_ExecFuncPtr()
Caution
The MIS_FuncPtr() , MIS_SetExecPtr() and MIS_ExecFuncPtr() are very powerful functions with which you
can build amazing features such as code that modifies itself. However they are also very dangerous. It goes far
beyond macros and is also much quicker because it never implies a compilation process of any sort.
If the parameters that are passed to this function do not correspond to the ones that are expected by the
function pointed to by the internal code pointer, unpredictable results will happen, often terminating the
current application by causing an illegal operation.
Syntax
MIS_ExecFuncPtr( <parameters> )  xValue
Parameters
<parameters> list of parameters coping with the parameters of the function that should be executed.
Returns
Example
LOCAL FuncPtr
FuncPtr = MIS_FuncPtr("STR_mirror")
MIS_SetExecPtr( FuncPtr )
? MIS_ExecFuncPtr( "Hello" ) && "olleH"
ENDIF

MIS_false() : Always returns a logical .F..
Comment
This function will help you get rid of any return value when multiple function calls are made. This can be applied to a
VALID clause for example.
Syntax
MIS_false([[[[[[[[[[xExpr1,] xExpr2,] xExpr3,] xExpr4,] ;
xExpr5,] xExpr6,] xExpr7,] xExpr8,] xExpr9,] ;
xExpr10 )  .F.
Parameters
You can go up to 10 parameters that are totally disregarded by the function. The function acts as it was passed no
parameter.
Returns
.F. the function always returns .F..
MIS_FuncPtr() : Returns a function pointer to a specified

function contained in FOCUS.FLL.
Alias
DDA_FuncPtr()
Syntax
MIS_FuncPtr( cFunction )  nPointer
Parameters
cFunction function to look for in FOCUS.FLL or –1 if the function was not found.
Returns
Example
DISPLAY STATUS
&& You should have a list such as the one that follows:
BMP_BITS 10001490
BMP_COLORS 100014B0
BMP_HEADER 100014D0
BMP_HEIGHT 10001450
BMP_ISBMP 10001210
BMP_WIDTH 10001470
CD_BAYOPE 1000B860
CD_BAYCLO 1000B890
CD_CANEJE 1000BA40
CD_CANPLA 1000BAA0
<etc.>
? NUM_hexa( MIS_FuncPtr( "CD_CANPLA" ) ) && 1000BAA0

MIS_GetCommonSlot() : Gets/Sets the contents of a shared
memory slot.
Remark
Starting with version 6.0 of FOCUS.FLL , the library provides now an easy way to determine whether an application is
already loaded or not. It does it by having a common slot of memory that is shared amongst all instances of
FOCUS.FLL (please note that instances of FOCUS.FLL are not the same when several physical libraries are used)
This common memory is actually a buffer of 256 bytes. Applications can place unique signatures in that buffer when
they load, and can discard their own signature when they exit. By checking what's in that common memory storage
place, application developers can easily determine whether their application is already loaded in memory or not.
Because FOCUS.FLL is a common resource for many developers, people that want to interact with this common slot
also have to determine what signatures they'll use.
Alias
MIS_SetCommonSlot(), GetCommonSlot(), SetCommonSlot()
Syntax
MIS_GetCommonSlot( [szNewSlot] )  szSlot
Parameters
szNewSlot the new value that will be assigned to the common slot. Never pass a parameter that is longer
than 256 bytes unless you absolutely want to cause illegal operations!
Returns
szSlot current slot value, prior to assign a new value to it.
Example
&& Imagine the following scenario : APPLI1 is loaded; It is the first time an
&& application loads FOCUS.FLL and it executes the following code :
LOCAL szApplName
LOCAL szSlot
SET LIBRARY TO "C:\COMMON\FOCUS.FLL"
m.szApplName = "APPLI1"
m.szSlot = GetCommonSlot()
IF ( ! EMPTY( m.szSlot ) )
m.szSlot = m.szSlot + "^" + m.szApplName
SetCommonSlot( m.szSlot )
ELSE
SetCommonSlot( m.szApplName )
ENDIF
? GetCommonSlot() && should report : "APPL1"
&& Now, you have a second application that loads and use FOCUS.FLL. It
&& currently executes the code that follows :
LOCAL m.szApplName
ELSE
ENDIF

? GetCommonSlot() && should report : "APPL1ÂPPL2"
*************************************************
&& Imagine the same scenario as before, but now the 2 applications load
&& 2 different FOCUS.FLL
LOCAL m.szApplName
SET LIBRARY TO "C:\MYAPP\FOCUS.FLL"
ELSE
ENDIF
&& Now, you have a second application that loads and use FOCUS.FLL
&& (but not the same physical file) and it currently executes
&& the code that follows :
LOCAL m.szApplName
ELSE
ENDIF
MIS_GetFocusUsage() : Gets the usage count of FOCUS.FLL.

Remark
Starting with version 6.0 of FOCUS.FLL , the library does have a common slot of memory that is shared amongst all
instances of FOCUS.FLL (please note that instances of FOCUS.FLL are not the same when several physical libraries
are used). Each SET LIBRARY TO FOCUS.FLL is registered and a counter is incremented; each RELEASE
LIBRARY FOCUS.FLL is also registered and the internal counter is decremented.
Syntax
MIS_GetFocusUsage()  nCounter
Parameters
None.
Returns
nCounter current value of the internal counter. This counter can only be queried and never can be set.

MIS_IsFunction() : Returns .T. if a specified function exists in
FOCUS.FLL.
Syntax
MIS_IsFunction( cFunction )  lExist
Parameters
cFunction function to look for in FOCUS.FLL .
Returns
lExist .T. if function cFunction exists; .F. otherwise.
Example
? MIS_IsFunction( "MIS_Vers" ) && .T.
MIS_knlmajor() : Returns the major version number of

KERNEL.DLL.
Alias
knlmajor()
Syntax
MIS_knlmajor()  nMajor
Parameters
None.
Returns
MIS_knlminor() : Returns the minor version number of

KERNEL.DLL.
Alias
knlminor()
Syntax
MIS_knlminor()  nMinor
Parameters
None.
Returns

MIS_knlvers() : Returns the version number of KERNEL.DLL.
Alias
Knlvers(), knlver(), knlversion()()
Syntax
MIS_knlvers()  cVersion
Parameters
None.
Returns
cVersion version number identifier.
Example
? MIS_knlvers() && "KERNEL.DLL - Pat Boens - 17 June 1998 18:45-v3.0"
MIS_LastVersion() : Returns the file stamp of MIS functions.

Remark
Syntax
MIS_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\MISC.C-Mon Oct 19 15:55:22 1998" .
MIS_major() : Returns the major version number of

FOCUS.FLL.
Alias
major()
Syntax
MIS_major()  nMajor
Parameters
None.
Returns
Example
LOCAL lWrongVersion
IF ( MIS_major() >= 4 )
IF ( MIS_minor() >= 80 )
lWrongversion = .F.
ELSE
lWrongVersion = .T.
ENDIF
ELSE
lWrongVersion = .T.
ENDIF
IF ( lWrongVersion )
? "You should upgrade FOCUS.FLL"
ENDIF
MIS_minor() : Returns the minor version number of

FOCUS.FLL.
Alias
minor()
Syntax
MIS_minor()  nMinor
Parameters
None.
Returns
Example
LOCAL lWrongVersion
IF ( MIS_major() >= 4 )
IF ( MIS_minor() >= 80 )
lWrongversion = .F.
ELSE
lWrongVersion = .T.
ENDIF
ELSE
lWrongVersion = .T.
ENDIF
IF ( lWrongVersion )
? "You should upgrade FOCUS.FLL"
ENDIF
MIS_nothin() : Does not do anything !

Alias
Nothing(), MIS_Nothing()
Syntax
MIS_nothin([[[[[[[[[[xExpr1,] xExpr2,] xExpr3,] xExpr4,] ;
xExpr10 )  .T.

Parameters
parameter.
Returns
.T. the function always returns .T.. Even though the function is not supposed to return anything,
Visual FoxPro gives a .T. which is the default for a function/procedure/method that does not
contain an explicit return.
Example
ON KEY LABEL ESCAPE =MIS_nothin()
MIS_OnlineDocVers() : Returns the version of the FOCUS

online documentation.
Alias
MIS_OnlineDocVer(), MIS_OnlineDocVersion()
Syntax
MIS_OnlineDocVers()  szOnlineDocVers
Parameters
None.
Returns
szOnlineDocVers online documentation version.
Example
? MIS_OnlineDocVers() && "FOCUS Online documentation by Pat Boens & Korakot Leelachareanwaranon -
Tue Apr 20 21:37:38 1999-v 6.03"
See also
MIS_major() , MIS_minor() , MIS_knlmajor() , MIS_knlminor() , MIS_DocVers() , MIS_credits() ,
MIS_vers()
MIS_OutputDebugString() : Sends a string to the debugger for

the current application.
Remark
There are lot of utilities that monitor the output and redirects these to a given window. The utilities that we used to do
this are located on the Systems Internals web site (http://www.sysinternals.com): DebugView/EE for Windows NT or
for Win9x.
Syntax
MIS_OutputDebugString( szStr )  .T.
Parameters
szStr string to be sent to the debugger.

Returns
MIS_NumberOfFunctions() : Number of functions included in

FOCUS.FLL.
Syntax
MIS_NumberOfFunctions()  nFunctions
Parameters
None.
Returns
nFunctions number of functions supported by FOCUS.FLL including all aliases (For example, the
MIS_Vers() function counts actually for 3 functions because it is known under 3 different
names).
Example
? MIS_vers() + " / Support for " + ALLTRIM(STR(MIS_NumberOfFunctions())) + " functions"
&& "FOCUS.FLL by Pat Boens; Documentation by Pat Boens & Pete Cuiry - 10 October 1998 10:24-v 5.13 /
Support for 1130 functions"
&& The following example lists all functions starting with "STR" (all string functions)
Filter( "STR" )
FUNCTION Filter( szPrefix )
LOCAL szAllFunctions
LOCAL nFunctions
LOCAL nArgs
LOCAL i
LOCAL OldSep
nArgs = PCOUNT()
szPrefix = IIF ( nArgs == 0,"*",szPrefix + "_*" )
SET LIBRARY TO "c:\focus\5.0\winrel\focus.fll"
szAllFunctions = MIS_AllFunctions()
nFunctions = MIS_NumberOfFunctions()
FOR i = 1 TO nFunctions
szFunction = STR_ntoken( i,szAllFunctions )
IF ( LIKE( cPrefix,szFunction ) )
? szFunction
ENDIF
NEXT
SET LIBRARY TO
RETURN ( .NULL. )

MIS_SetExecPtr() : Assigns the internal execution pointer to a
given value.
Alias
DDA_SetExecPtr()
Syntax
MIS_SetExecPtr( nPointer )  .T.
Parameters
Returns
Example
LOCAL FuncPtr
FuncPtr = MIS_FuncPtr("STR_mirror")
MIS_SetExecPtr( FuncPtr )

? MIS_ExecFuncPtr( "Hello" ) && "olleH"
ENDIF
MIS_true() : Always returns a logical .T.

Comment
This function will help you get rid of any return value when multiple function calls are made. This can be applied to a
VALID clause.
Syntax
MIS_true([[[[[[[[[[xExpr1,] xExpr2,] xExpr3,] xExpr4,] ;
xExpr10 )  .T.
Parameters
parameter.
Returns
MIS_vers() : returns the version number of FOCUS.FLL.

Alias
MIS_ver(), MIS_version()

Syntax
MIS_vers()  szVersion
Parameters
None.
Returns
szVersion version as string.
Example
? MIS_vers() && "FOCUS.FLL - Mon Sep 25 10:21:20 2000-v 7.88"
See also
MIS_major() , MIS_minor() , MIS_knlmajor() , MIS_knlminor() , MIS_DocVers() ,
MIS_OnlineDocVers() , MIS_credits()

Menu Functions
Menu Functions

Menu Functions
MNU_AddItem() : Adds an item to a menu created with

MNU_Make().
Syntax
MNU_AddItem( nMenuHandle,nChoice,szCaption[,lEnabled[,lChecked]] ) lSuccess
Parameters
nMenuHandle the handle identifying the menu to which an item must be added.
nChoice the value that must be returned by the MNU_Play() function if the user has selected this item.
szCaption the caption of the item. Use "\-" to add a separation line. Use '&' to create accelerators.
lEnabled optional parameter. Indicates whether the item must appear enabled or disabled. By default,
the item is enabled.
lChecked optional parameter. Indicates whether the item must appear being checked or not. By default,
the item is NOT checked.
Returns
lSuccess .T. if item added successfully; .F. if not.
Example
LOCAL nMainMenu
LOCAL nMenuCountries
LOCAL nMenuCities
LOCAL nMenuCurrencies
LOCAL nMenuFriends
LOCAL nCountries
LOCAL nCities
LOCAL nCurrencies
LOCAL nFriends
LOCAL nChoice
&& Let's start by creating 5 menus

m.nMainMenu = MNU_Make()
m.nMenuCountries = MNU_Make()
m.nMenuCities = MNU_Make()
m.nMenuCurrencies = MNU_Make()
m.nMenuFriends = MNU_Make()
&& Let's create some baselines for the retun values

m.nCountries = 1000
m.nCities = 2000
m.nCurrencies = 3000
m.nFriends = 4000
IF ( m.nMainMenu != -1 .AND. ;
m.nMenuCountries != -1 .AND. ;
m.nMenuCities != -1 .AND. ;
m.nMenuCurrencies != -1 .AND. ;
m.nMenuFriends != -1)
&& We will prepare the menu for the countries first

i = m.nCountries + 1 && Return value if item selected
MNU_AddItem( m.nMenuCountries,i,"Belgium" ) && Create the item
i = i + 1 && Return value if item selected
MNU_AddItem( m.nMenuCountries,i,"France" ) && Create the item
MNU_AddItem( m.nMenuCountries,i,"Germany" ) && Create the item
MNU_AddItem( m.nMenuCountries,i,"Netherlands" ) && Create the item

Menu Functions
MNU_AddItem( m.nMenuCountries,i,"United Kingdom" ) && Create the item
MNU_AddItem( m.nMenuCountries,i,"United States of America" ) && Create the item
&& We will attach the menu of friends to the Brussels stuff

&& So we first need to create this submenu
i = m.nFriends + 1 && Return value if item selected
MNU_AddItem( m.nMenuFriends,i,"Jean" ) && Create the item
MNU_AddItem( m.nMenuFriends,i,"Bernard" ) && Create the item
MNU_AddItem( m.nMenuFriends,i,"Michel" ) && Create the item
MNU_AddItem( m.nMenuFriends,i,"Didier" ) && Create the item
MNU_AddItem( m.nMenuFriends,i,"Vanessa" ) && Create the item
&& We will prepare the menu for the cities next

i = m.nCities + 1 && Return value if item selected
MNU_AddMenu( m.nMenuCities,m.nMenuFriends,"Brussels" ) && Attach menu Friends to Cities
MNU_AddItem( m.nMenuCities,i,"Paris" ) && Create the item
MNU_AddItem( m.nMenuCities,i,"Berlin" ) && Create the item
MNU_AddItem( m.nMenuCities,i,"Amsterdam" ) && Create the item
MNU_AddItem( m.nMenuCities,i,"London" ) && Create the item
MNU_AddItem( m.nMenuCities,i,"&New York" ) && Create the item (accelerator)
&& Finally, we prepare the menu for the currencies next

i = m.nCurrencies + 1 && Return value if item selected
MNU_AddItem( m.nMenuCurrencies ,i,"EUR" ) && Create the item
MNU_AddItem( m.nMenuCurrencies ,i,"GBP" ) && Create the item
MNU_AddItem( m.nMenuCurrencies ,i,"USD" ) && Create the item
&& Let's attach the three submenus to the main menu

MNU_AddMenu( m.nMainMenu,m.nMenuCountries ,"Countries" )
MNU_AddMenu( m.nMainMenu,m.nMenuCities ,"Cities" )
MNU_AddMenu( m.nMainMenu,m.nMenuCurrencies,"Currencies" )
&& Now let's add some fancy items (a separation line, a disabled
&& item, a disabled and though checked item, and a checked item)
MNU_AddItem( m.nMainMenu,0,"\-" ) && Add a separation line
i = 0 && Return value if item selected
MNU_AddItem( m.nMainMenu,i,"Item disabled",.F. ) && Create the item
MNU_AddItem( m.nMainMenu,i,"Item disabled and checked",.F.,.T. ) && Create the item
MNU_AddItem( m.nMainMenu,i,"Item checked",.T.,.T. ) && Create the item
&& Play the menu now!!!

m.nChoice = MNU_Play( m.nMainMenu )
&& Display the choice we've made

? "The choice you made is",m.nChoice
&& Free the internal memory taken by each menu

? MNU_Destroy( m.nMenuFriends ), ;
MNU_Destroy( m.nMenuCountries ), ;
MNU_Destroy( m.nMenuCurrencies ), ;
MNU_Destroy( m.nMenuCities ), ;
MNU_Destroy( m.nMainmenu )

Menu Functions
ENDIF
Note the
accelerator
See also
MNU_Destroy() , MNU_Make() , MNU_Play() , MNU_AddMenu() .
MNU_AddMenu() : Attach a submenu to a menu.

Syntax
MNU_AddMenu( nMainMenuHandle,nSubMenu,szCaption ) lSuccess
Parameters
nMainMenu the menu handle nSubMenu must be attached to.
nSubMenu the menu handle that identifies the menu to be attached to nMainMenu .
szCaption the caption of the submenu.
Returns
lSuccess .T. if nSubMenu attached to nMainmenu ; .F. if not.
Example
LOCAL nMainMenu
LOCAL nMenuCities
LOCAL nMenuFriends
LOCAL nCountries
LOCAL nCities
LOCAL nCurrencies
LOCAL nFriends
LOCAL nChoice


m.nCountries = 1000
m.nCities = 2000

Menu Functions
m.nFriends = 4000



MNU_AddItem( m.nMenuCities,i,"New York" ) && Create the item



Menu Functions



ENDIF
See also
MNU_Play() , MNU_Destroy() , MNU_AddItem() , MNU_AddMenu() .
MNU_create() : Creates a context menu at the position of the

mouse.
Alias
CreateContextMenu()
Syntax
MNU_create( szMenuDef ) nChoice
Parameters
szMenuDef a string containing the definition of the menu. The string is tokenized. Each token is separated
from another by a caret ( ^). Separation lines can be defined by using a "\-" token. Separation
lines aren't taken into account for the final choice.
If an option of the menu is prefixed by "\G\" , the option is displayed grayed out; if an option
of the menu is prefixed with "\C\" , the option is displayed as checked.
Returns
nChoice the position of the choice or 0 if the menu was cancelled. The separation lines aren't counted for
the final choice.
Example
LOCAL szMenu
szMenu = "First choice^Second choice^\-^Final choice"

Menu Functions
? MNU_create( szMenu )
&& Example where the second option is checked.

? MNU_create("Hello^\C\World")
&& Example where the second option is grayed out.

? MNU_create("Hello^\G\World")
See also
MNU_create2()
MNU_Destroy() : Destroys an internal menu structure created

with MNU_Make().
Syntax
MNU_Destroy( nMenuHandle ) lSuccess
Parameters
nMenuHandle the menu handle identifying the menu to be destroyed.
Returns
lSuccess .T. if menu destroyed; .F. if not.
Example
LOCAL nMainMenu
LOCAL nMenuCities
LOCAL nMenuFriends
LOCAL nCountries
LOCAL nCities
LOCAL nCurrencies
LOCAL nFriends
LOCAL nChoice


m.nCountries = 1000
m.nCities = 2000
m.nFriends = 4000

Menu Functions






Menu Functions


ENDIF
See also
MNU_Play() , MNU_Make() , MNU_AddItem() , MNU_AddMenu() .
MNU_Make() : Creates an internal menu structure suitable for

context menus.
Syntax
MNU_Make() nMenuHandle
Parameters
None.
Returns
nMenuHandle a menu handle or -1 if menu cannot be created.
Example
LOCAL nMainMenu
LOCAL nMenuCities
LOCAL nMenuFriends
LOCAL nCountries
LOCAL nCities
LOCAL nCurrencies
LOCAL nFriends
LOCAL nChoice


m.nCountries = 1000

Menu Functions
m.nCities = 2000
m.nFriends = 4000






Menu Functions



ENDIF
See also
MNU_Play() , MNU_Destroy() , MNU_AddItem() , MNU_AddMenu() .
MNU_Play() : Plays a menu created by MNU_Make().

Syntax
MNU_Play( nMenuHandle ) nChoice
Parameters
nMenuHandle the menu handle identifying the menu to be played.
Returns
nChoice a number identifying the choice made by the user. It corresponds to the nChoice parameter of
the MNU_AddItem() function.
Example
LOCAL nMainMenu
LOCAL nMenuCities
LOCAL nMenuFriends
LOCAL nCountries
LOCAL nCities
LOCAL nCurrencies
LOCAL nFriends
LOCAL nChoice


Menu Functions

m.nCountries = 1000
m.nCities = 2000
m.nFriends = 4000






Menu Functions



ENDIF
See also
MNU_Destroy() , MNU_Make() , MNU_AddItem() , MNU_AddMenu() .

Mouse Functions
Mouse Functions

Mouse Functions
MOU_ClipCursor() : Restricts the cursor to the specified area.

Remark
MOU_ClipCursor( .NULL. ) is identical to MOU_FreeClipCursor() .MOU_ClipCursor() affects your whole
Windows environment.
Alias
ClipCursor()
Syntax
MOU_ClipCursor( nTop,nLeft,nBottom,nRight ) lSuccess
Or…
MOU_ClipCursor( .NULL. ) lSuccess
Parameters
nTop the top position of the rectangular area the cursor will be restricted to.
nLeft the left position of the rectangular area the cursor will be restricted to.
nBottom the bottom position of the rectangular area the cursor will be restricted to.
nRight the right position of the rectangular area the cursor will be restricted to.
Or…
.NULL. when the .NULL. value is passed to MOU_ClipCursor() the function behaves like
MOU_FreeClipCursor() . When used so, the ClipCursor() alias is performing exactly as
documented in the Win32 API.
The nTop , nLeft , nBottom and nRight parameters delimit a rectangular area described in absolute pixel screen
coordinates. Therefore, should the developer want to restrict the coordinates to a particular region of a given form,
then he'll need to adjust the relative position to absolute screen position. What's more, he should notice that he needs
to pay attention to Window titles, menu height, form border width, form border height, etc. In the example below, the
accurate calculations were performed.
Returns
Example
oClipForm = CREATEOBJECT( "ClipForm" )
oClipForm.Show()
DEFINE CLASS clipForm AS form
Name = "Dvlform1"
ADD OBJECT dvlseparator1 AS dvlseparator WITH ;

Top = 202 , ;
Left = 150 , ;
Width = 210 , ;
Height = 10 , ;
Name = "Dvlseparator1" , ;
Line1.Name = "Line1" , ;
Line4.Name = "Line4"
ADD OBJECT dvlbutton1 AS dvlbutton WITH ;

Top = 192 , ;
Left = 361 , ;

Mouse Functions
Height = 25 , ;
Width = 10 , ;
Caption = "" , ;
Enabled = .T. , ;
Name = "Dvlbutton1"
ADD OBJECT dvllabel1 AS dvllabel WITH ;

Caption = "0" , ;
Height = 15 , ;
Left = 150 , ;
Top = 220 , ;
Width = 8 , ;
Name = "Dvllabel1"
ADD OBJECT shape1 AS shape WITH ;

Top = 10 , ;
Left = 150 , ;
Height = 150 , ;
Width = 150 , ;
FillStyle = 4 , ;
BackColor = RGB(255,255,0) , ;
Name = "Shape1"
ADD OBJECT shape2 AS shape WITH ;

Top = 10 , ;
Left = 310 , ;
Height = 150 , ;
Width = 52 , ;
FillStyle = 4 , ;
BackColor = RGB(255,0,0) , ;
FillColor = RGB(255,255,255) , ;
BorderColor = RGB(0,0,0) , ;
Name = "Shape2"
*--------------------------------------------------------------*
PROCEDURE dvlbutton1.MouseMove( nButton,nShift,nXCoord,nYCoord )
LOCAL nPercent
IF ( nButton == 1 )
This.Left = nXCoord
nPercent = ( ( nXCoord - ThisForm.dvlSeparator1.Left ) / ;
ThisForm.dvlSeparator1.Width ) * 100
ThisForm.dvlLabel1.caption = ALLTRIM(STR(nPercent))
ThisForm.Shape1.Width = 150 * ( nPercent / 100 )
ThisForm.Shape1.Height = 150 * ( nPercent / 100 )
ThisForm.Shape2.Height = ThisForm.Shape1.Height
ThisForm.Shape2.Left = ThisForm.Shape1.Left + ;
ThisForm.Shape1.Width + 10
ENDIF
ENDPROC
*--------------------------------------------------------------*
PROCEDURE dvlbutton1.MouseUp( nButton,nShift,nXCoord,nYCoord )

MOU_FreeClipCursor()
ENDPROC
*--------------------------------------------------------------*
PROCEDURE dvlbutton1.MouseDown( nButton,nShift,nXCoord,nYCoord )
LOCAL nTitleHeight
LOCAL nBorderHeight
LOCAL nMenuHeight
LOCAL nBorderWidth
nTitleHeight = SYSMETRIC(9)
nBorderHeight = SYSMETRIC(4)
nMenuHeight = SYSMETRIC(20)
nBorderWidth = SYSMETRIC(3)
nTop = _SCREEN.Top + ThisForm.Top + ThisForm.Dvlseparator1.Top + ;

Mouse Functions
( 2 * nTitleHeight ) + nMenuHeight + ( 2 * nBorderHeight )
nLeft = _SCREEN.Left + ThisForm.Left + ;
ThisForm.Dvlseparator1.Left + ( 2 * nBorderWidth )
MOU_ClipCursor( nTop , ;
nLeft , ;
nTop + ThisForm.Dvlseparator1.Height, ;
nLeft + ThisForm.Dvlseparator1.Width ) && - This.Width)
ENDPROC
*--------------------------------------------------------------*
PROCEDURE shape1.RightClick()
ENDPROC
*--------------------------------------------------------------*
PROCEDURE shape1.Click()
LOCAL nTitleHeight
LOCAL nBorderHeight
LOCAL nMenuHeight
LOCAL nBorderWidth
nTop = _SCREEN.Top + ThisForm.Top + This.Top + ;

nLeft = _SCREEN.Left + ThisForm.Left + This.Left + ( 2 * nBorderWidth )
nLeft , ;
nTop + This.Height, ;
nLeft + This.Width ) && - This.Width)
ENDPROC
*--------------------------------------------------------------*
PROCEDURE shape2.Click()
LOCAL nTitleHeight
LOCAL nBorderHeight
LOCAL nMenuHeight
LOCAL nBorderWidth
nTop = _SCREEN.Top + ThisForm.Top + This.Top + ;

nLeft = _SCREEN.Left + ThisForm.Left + This.Left + ( 2 * nBorderWidth )
nLeft , ;
nTop + This.Height, ;
nLeft + This.Width ) && - This.Width)
ENDPROC
*--------------------------------------------------------------*
PROCEDURE shape2.RightClick
ENDPROC
*--------------------------------------------------------------*
ENDDEFINE

Mouse Functions
See also
MOU_FreeClipCursor() : Clears a previously set cursor

clipping region.
Remark
MOU_FreeClipCursor() is identical to MOU_ClipCursor( .NULL. ) .
Alias
FreeClipCursor() .T.
Syntax
MOU_FreeClipCursor() .T.
Parameters
None.
Returns
Example
See MOU_ClipCursor() example.
See also
MOU_ClipCursor()
MOU_isdown() : Is the left mouse button down?

Comment
Identical to MDOWN() . Does not require to start the FOCUS.FLL internal event handler (EVE_start() ).
Syntax
MOU_isdown() lIsDown
Parameters
None.
Returns
lIsDown .T. if the left mouse button is down
Example
&& Waiting until the left button is depressed
DO WHILE( MOU_isdown() )
ENDDO

Mouse Functions
MOU_isLeftMouseDown() : Is the left mouse button down?
Comment
Requires to start the FOCUS.FLL internal event handler (EVE_start() ). It is during the capture of internal
events that FOCUS.FLL stores the internal state of the mouse buttons. This can be useful in some circumstances
when you cannot rely on MouseDown() or MouseUp() events.
Syntax
MOU_IsLeftMouseDown() lIsSet
Parameters
None.
Returns
lIsSet .T. if the left mouse button is down.
MOU_isLeftMouseUp() : Is the left mouse button up?

Comment
Syntax
MOU_IsLeftMouseUp() lIsSet
Parameters
None.
Returns
lIsSet .T. if the left mouse button is up.
MOU_isMiddleMouseDown() : Is the middle mouse button

down?
Comment
Syntax
MOU_IsMiddleMouseDown() lIsSet
Parameters
None.

Mouse Functions
Returns
lIsSet .T. if the middle mouse button is down.
MOU_isMiddleMouseUp() : Is the middle mouse button up?

Comment
Syntax
MOU_IsMiddleMouseUp() lIsSet
Parameters
None.
Returns
lIsSet .T. if the middle mouse button is up.
MOU_isRightMouseDown() : Is the right mouse button down?

Comment
Syntax
MOU_IsRightMouseDown() lIsSet
Parameters
None.
Returns
lIsSet .T. if the right mouse button is down.
MOU_isRightMouseUp() : Is the right mouse button up?

Comment
Syntax
MOU_IsRightMouseUp() lIsSet

Mouse Functions
Parameters
None.
Returns
lIsSet .T. if the right mouse button is up.
MOU_LastVersion() : Returns the file stamp of MOU functions.

Remark
Syntax
MOU_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\MOUSE.C-Mon Oct 19 15:55:22 1998" .
MOU_LeftDown() : Simulates a left button down.

Syntax
MOU_LeftDown() .T.
Parameters
None.
Returns
Example
* Simulates a click where the mouse is
MOU_LeftDown()
MOU_LeftUp()
MOU_LeftUp() : Simulates a left button up.

Syntax
MOU_LeftUp() .T.
Parameters
None.

Mouse Functions
Returns
Example
* Simulates a click where the mouse is
MOU_LeftDown()
MOU_LeftUp()
MOU_MiddleDown() : Simulates a middle button down.

Syntax
MOU_MiddleDown() .T.
Parameters
None.
Returns
MOU_MiddleUp() : Simulates a middle button up.

Syntax
MOU_MiddleUp() .T.
Parameters
None.
Returns
MOU_RightDown() : Simulates a right button down.

Syntax
MOU_RightDown() .T.
Parameters
None.
Returns
Example
* Simulates a right click where the mouse is
MOU_RightDown()
MOU_RightUp()

Mouse Functions
MOU_RightUp() : Simulates a right button up.
Syntax
MOU_RightUp() .T.
Parameters
None.
Returns
Example
MOU_RightDown()
MOU_RightUp()
MOU_Swap() : Swap mouse buttons.

Remarks
Button swapping is provided as a convenience to people who use the mouse with their left hands. The MOU_Swap()
function is usually called by Control Panel only. Although an application is free to call the function, the mouse is a
shared resource and reversing the meaning of its buttons affects all applications.
Alias
MOU_SwapButton(), MOU_SwapButtons(), MOU_SwapMouseButton(), MOU_SwapMouseButtons(), SwapMouseButton().
Syntax
MOU_Swap( lSwap ) lSuccess
Parameters
lSwap .T. to swap mouse buttons; .F. to restore mouse buttons.
Returns
lSuccess .T.. if the function was successful; .F. if not.
Example
IF ( MOU_Swap( .T. ) )
? "Brace yourself! Enjoy the mouse now!"
ENDIF

MQSeries Functions
MQSeries Functions

MQSeries Functions
Functions Synopsis
MQSeries is the leading product in the field of messaging and queuing. It is vastly used in Banks and Pharmaceutical
Industries and it has proved to be stable and reliable. FOCUS.FLL per se does not provide access to the MQSeries
API: FOCUSMQS.FLL and FOCUSMQC.FLL do!
Sending a message
1. Connect to the Queue Manager
2. Open the target queue in “PUT” mode
3. Send the message
4. Close the target queue
5. Disconnect from the Queue Manager
Reading a message
2. Open the queue for incoming message sin “GET” mode
3. Read the message
4. Close the queue
There is quite some overhead while connecting/disconnecting to/from a Queue Manager. Opeing/Closing queues is
faster but still creates some overhead. Therefore you might want to connect only once to the Queue Manager and open
only once the queue.
Sending multiple messages
2. Open the target queue in “PUT” mode
3. Send message1; Send message2; send message3; …
Reading multiple messages
2. Open the target queue in “GET” mode
3. Read message1; read message2; read message3; …

MQSeries Functions
*************
UNDER CONSTRUCTION
int FW_MQ_connect( XBASE_PARAMETERS );
int FW_MQ_open( XBASE_PARAMETERS );
int FW_MQ_openBrowse( XBASE_PARAMETERS );
int FW_MQ_put( XBASE_PARAMETERS );
int FW_MQ_get( XBASE_PARAMETERS );
int FW_MQ_getBrowse( XBASE_PARAMETERS );
int FW_MQ_close( XBASE_PARAMETERS );
int FW_MQ_disconnect( XBASE_PARAMETERS );
int FW_MQ_GetLastError( XBASE_PARAMETERS );
int FW_MQ_commit( XBASE_PARAMETERS );
int FW_MQ_inquire( XBASE_PARAMETERS );
int FW_MQ_BackOut( XBASE_PARAMETERS );
int FW_MQ_SetAttribute( XBASE_PARAMETERS );
int FW_MQ_getLastDate( XBASE_PARAMETERS );
int FW_MQ_getLastTime( XBASE_PARAMETERS );
int FW_MQ_getLastApplType( XBASE_PARAMETERS );
int FW_MQ_getLastApplName( XBASE_PARAMETERS );
*************

MQSeries Functions
MQ_close() : Closes the current queue.

Syntax
MQ_close()  nSuccess
Parameters
None.
Returns
nSuccess 0 if the current queue is successfully closed; otherwise, please refer to your MQSeries
documentation.
Example
?????
MQ_connect() : Connects to the Queue Manager.

Syntax
MQ_connect( szQueueManager )  nSuccess
Parameters
szQueueManager MQSeries Queue Manager.
Returns
nSuccess 0 if successfully connected; otherwise, please refer to your MQSeries documentation.
Example
?????
MQ_disconnect() : Disconnects from the Queue Manager.

Syntax
MQ_disconnect()  nSuccess
Parameters
None.
Returns
nSuccess 0 if successfully disconnected; otherwise, please refer to your MQSeries documentation.
Example
?????
MQ_open() : Opens a Queue.

Syntax
MQ_open( szQueue,szMode )  nSuccess

MQSeries Functions
Parameters
szQueue MQSeries Queue.
szMode opening mode of szQueue.
Value Description
"GET" Opens the queue in read mode
"PUT" Opens the queue in write mode
"GET+PUT" Opens the queue in read/write mode
Returns
nSuccess 0 if szQueue is successfully opened; otherwise, please refer to your MQSeries documentation.
Example
??????????

Messaging Functions
Messaging Functions

Messaging Functions
Functions Synopsis
FOCUS.FLL provides a basic messaging mechanism. It is working on the Post Office scheme, which basically means
that all messages are stored in a common place: the Post Office!
The Post Office is actually 2 things :
1. it is a common place in which all messages are stored
2. it is a Settings File in which all accounts are defined.
Appli1 Appli7
Appli2 Post
Office
Appli3 Appli5
Appli4 Appli6
For different applications to exchange messages, they all have to agree on a common Post office and a common
Settings File. This is done through the MSG_PostOffice() function. For example, by issuing the following command,
many different applications specify they rely on the Post Office located on the WALK2227 machine, in the Post
Office directory, and that the Settings File to take in consideration is the PO.INI :
MSG_PostOffice( "\\WALK2227\Post Office\PO.INI" )
Each application should be uniquely identified. In our example, we have 7 different applications running on different
machines but they all access one common central Post Office and they all use the same Settings File.
Structure of the Settings File
[MESSAGES]
Counter=111
[SEQUENCING]
next=111
[ACCOUNTS]
APPLI1=00000001
APPLI2=00000002
APPLI3=00000003

Messaging Functions
<etc.>
[DEADLETTER]
Dir=Dead
[APPLI1]
Dir=00000001
Comment=Elected PC
[APPLI]
Dir=00000002
Comment=mailbox of COMPAQ 166 MHz
[APPLI3]
Dir=00000003
Comment=mailbox of Dominique's PC
Post Office
Technically, the Post Office is nothing else but a shared directory on a network. Each application (recipient) is uniquely
identified and is granted its own directory within the Post Office. For example, on the WALK2227 machine, the central
Post office is located in the Post Office directory, and Appli1 is hooked to the 00000001 directory within the
Post Office; Appli2 is hooked to the 00000002 directory, and so on (according to the structure of the Settings File).
How To Work With Messaging Functions?
Imagine the following situation : you have 3 applications, Appli1 , Appli2 and Appli3 . Appli1 and Appli2 are
located on the MACHINE1 computer while Appli3 is placed on MACHINE2 . You want the Post Office to be located on
a third machine, MACHINE3 , in the BP directory. The first thing to do is to create a Post Office Settings File similar to:
[MESSAGES]
Counter=0
[SEQUENCING]
next=0
[ACCOUNTS]
APPLI1=00000001
APPLI2=00000002
APPLI3=00000003
[DEADLETTER]
Dir=Dead
[APPLI1]
Dir=00000001
[APPLI]
Dir=00000002
[APPLI3]
Dir=00000003
You place this Settings File in the BP directory of the Post Office (\\MACHINE3\BP , a directory that you share for both
Read and Write operations) and you name it PO.INI . On MACHINE3 , directory BP, you will need to create the
subdirectories that each application is hooked to, in other words 00000001 , 00000002 , and 00000003 .
Now, you're ready to use Messaging Functions of FOCUS.FLL . For example, the following code that gets executed in
Appli1 will broadcast a message to the other two applications that are served by the same Post Office:
MSG_PostOffice( "\\MACHINE3\BP\PO.INI" )
IF ( ! MSG_Broadcast( "APPLI1","Subject","Category","This is my message" ) )

? "Not all recipients were served:",MSG_LastError()
ENDIF

Messaging Functions
As you can see, there is no mentioning of the machine an application is on for the Messaging Functions to work without
any problem.
Now one might ask : How do I know when a message has arrived? The answer is clear and obvious (for one that
already pointed a head in the direction of the Notification Functions) : you simply set a notification hook.
For example, Appli3 might want to monitor its own directory on the Post office to be warned whenever a new message
arrives. Therefore it simply needs to use the following code :
LOCAL nHandle
LOCAL lSubDir
#define MONITOR_LAST_WRITE 0x00000010
lSubDir = .T.
MSG_PostOffice( "\\MACHINE3\BP\PO.INI" ) && Specify which Post office
nHandle = NOT_set( "\\MACHINE3\BP\00000003", ; && Directory to watch

"MyMsgHandler" , ; && Proc called in case of message
lSubDir , ; && Watch also sub-directories
MONITOR_LAST_WRITE ) && Monitor last write changes
&& If invalid handle

IF ( nHandle == -1 )
? "Cannot set notification on this directory"
ELSE
NOT_frequency(1000) && Allows a delay of 1 second (1000 milliseconds)
ENDIF
PROCEDURE MyMsgHandler( n )
LOCAL cMessage
**********************************************************************
* PURPOSE : Whenever thios procedure is called it means that there is
* a new message coming in the mailbox of this application
**********************************************************************
&& Read the least recent message of this application

cMessage = MSG_read( "APPLI3" )
&& If we successfully read the message, display it

IF ( ! EMPTY( cMessage ) )
? cMessage
ENDIF
RETURN
An application can dynamically create multiple Post Offices although one and only one Post Office is the current Post
Office. To do so, it must call the MSG_CreatePostOffice() , and MSG_CreateAccount() functions of
FOCUS.FLL . This allows intelligent applications to dialog between each other beyond the knowledge of any user.
FOCUS.FLL provides also some statistical functions (although they are very few) to tighter control messages :
MSG_TotalMessagesSent() , MSG_BytesSent() , MSG_MessagesSent() , MSG_MessagesRead() ,
MSG_MessagesReceived() .

Messaging Functions
MSG_Broadcast() : Sends a message to all recipients of the

Post Office.
Syntax
MSG_Broadcast( szFrom,szSubject,szCategory,szBody )  lSuccess
Parameters
szFrom sender identification.
szSubject subject of the message.
szCategory category of the message.
szBody body of the message.
Returns
lSuccess .T. if message was successfully sent; .F. if not. There is no message sent to the sender.
Example
IF ( ! MSG_Broadcast( "ME","System","Life","ME still alive" ) )
? "Message cannot be sent",MSG_LastError()
ENDIF
MSG_BytesSent() : Total number of bytes sent with the current

Post Office.
Syntax
MSG_BytesSent()  nBytes
Parameters
None.
Returns
nBytes number of bytes sent. Only the body of a message is taken in account.
Example
? "Average message length:",MSG_BytesSent()/MSG_TotalMessagesSent()
MSG_count() : Counts the number of unread messages for a

given recipient.
Alias
MSG_MessagesUnread()
Syntax
MSG_count( szRecipient )  nMessages

Messaging Functions
Parameters
szRecipient recipient identification.
Returns
nMessages the number of waiting messages or -1 if the recipient is unknown.
Example
? MSG_PostOffice( "C:\PO.INI" )
? MSG_count( "APPLI5" ) && 0
? MSG_count( "UNKNOWN RECIPIENT" ) && -1
? MSG_send( "APPLI1","APPLI5","Subject","Category",TTOC(DATETIME()) ) && .T.
? MSG_send( "APPLI1","APPLI5","Subject","Category",TTOC(DATETIME()) ) && .T.
MSG_CreateAccount() : Creates an account in the current Post

Office.
Syntax
MSG_CreateAccount( szAccount,szDir )  lSuccess
Parameters
szAccount account identification.
szDir directory in which messages for szAccount will be saved.
Returns
lSuccess .T. if the account was successfully created; .F. if not.
Example
IF ( MSG_CreatePostOffice( "\\WALK2227\Post Office\PO.INI" ) )
IF ( MSG_CreateAccount( "Account1","00000001" ) )
? "Account successfully recognized"
ENDIF
ELSE
? "Post Office cannot be created"
ENDIF
MSG_CreatePostOffice() : Creates a Post Office.

Syntax
MSG_CreatePostOffice( szPO )  lSuccess
Parameters
szPO Post Office Settings file and location.
Returns
lSuccess .T. if the Post Office was successfully created; .F. if not. The current Post Office is changed to
szPO .
Example
IF ( MSG_CreatePostOffice( "\\WALK2227\Post Office\PO.INI" ) )
IF ( MSG_CreateAccount( "Account1","00000001" ) )

Messaging Functions
? "Account successfully recognized"
ENDIF
ELSE
? "Post Office cannot be created"
ENDIF
MSG_DeleteAccount() : Deletes an account in the current Post

Office.
Syntax
MSG_DeleteAccount( szAccount,lSubdir )  lSuccess
Parameters
lSubdir deletes the directory in which messages of this account have been stored including all messages
that are still to be read.
Returns
lSuccess .T. if the account was successfully deleted; .F. if not. If the return value is .F., call
MSG_LastError() to get a more explicit reason.
MSG_DeleteUnread() : Deletes all pending messages of an

account.
Alias
MSG_DeleteAllMessages(), MSG_DeleteMessages(), DeleteMessages(), DeleteAllMessages()
Syntax
MSG_DeleteUnread( szAccount )  nDeleted
Parameters
Returns
nDeleted number of messages actually deleted or –1 if the account is not found or the current Post Office
not set.
Example
MOU_RightDown()
MOU_RightUp()
MSG_GetAllAccounts() : Gets all accounts that are defined in

the current Post Office.
Alias
MSG_GetAccounts(), MSG_Accounts()
Syntax
MSG_GetAllAccounts()  szAccounts

Messaging Functions
Parameters
None.
Returns
szAccounts a tokenized string with all accounts defined in the current Post Office. Each token is separated
by a ";".
Example
LOCAL nAccounts
LOCAL OldSep
LOCAL i
LOCAL szAccounts
m.OldSep = STR_setsep( ";" )
MSG_PostOffice( "\\MYSERVER\Bureau\BP.INI" )
IF ( MSG_IsPostOfficeAccessible() )
m.szAccounts = MSG_GetAllAccounts()
IF ( ! EMPTY( m.szAccounts ) )
m.nAccounts = STR_numtok( m.szAccounts )
FOR i = 1 TO m.nAccounts
? "Account : " + STR_ntoken( i,m.szAccounts )
NEXT
ENDIF
ENDIF
STR_setsep( m.OldSep )
MSG_GetDir() : Returns the mailbox directory of a given

recipient (absolute path).
Syntax
MSG_GetDir( szRecipient )  szDir
Parameters
Returns
szDir the mailbox directory or an empty string is the mailbox directory cannot be found in the
Settings File. When an empty string is returned, use the MSG_LastError() function to
determine the cause of the problem.
Example
? MSG_PostOffice("C:\PO.INI")
? MSG_GetDir("APPLI5") && "C:\00000005"
See also
MSG_GetSubDir()

Messaging Functions
MSG_GetSep() : Returns the separator that is used internally
by FOCUS.FLL to tokenize a message.
Syntax
MSG_GetSep()  szSep
Parameters
None.
Returns
szSep the separator used internally by FOCUS.FLL to tokenize a message.
Example
LOCAL cMessage
LOCAL OldSep
LOCAL szFrom
LOCAL szTo
LOCAL szDateTime
LOCAL szSubject
LOCAL szCategory
LOCAL szBody
LOCAL nTokens
szMessage = MSG_Read( "ME" )
IF ( EMPTY( szMessage ) )
? "Empty message"
ELSE
OldSep = STR_setsep( MSG_GetSep() )
nTokens = STR_numtok( szMessage )
IF ( nTokens == 6 )
szFrom = STR_ntoken( 1,szMessage )
szTo = STR_ntoken( 2,szMessage )
szDateTime = STR_ntoken( 3,szMessage )
szSubject = STR_ntoken( 4,szMessage )
szCategory = STR_ntoken( 5,szMessage )
szBody = STR_ntoken( 6,szMessage )
ELSE
? "Unexpected number of tokens"
ENDIF
ENDIF
MSG_GetSubDir() : Returns the mailbox directory of a given

recipient (relative path).
Syntax
MSG_GetSubDir( szRecipient )  szDir
Parameters
Returns
szDir the mailbox directory or an empty string is the mailbox directory cannot be found in the
Settings File. When an empty string is returned, use the MSG_LastError() function to
determine the cause of the problem.
Messaging Functions
Example
? MSG_GetSubDir("APPLI5") && "00000005"
See also
MSG_GetDir()
MSG_IsAccount() : Determines if the specified account is

known bt the current Post Office.
Syntax
MSG_IsAccount( szAccount )  lExist
Parameters
Returns
lExist .T. if szAccount exists in current Post Office; .F. if not.
Example
MSG_PostOffice( "C:\PO.INI" )
IF ( MSG_IsAccount( "SYSTEM" ) )
IF ( MSG_send( "ME","SYSTEM","Test","Category","My message" )
? "SYSTEM has received",MSG_MessagesReceived( "SYSTEM" ),"messages"
ENDIF
ENDIF
ENDIF
MSG_IsPostOfficeAccessible() : Determines whether the Post

Office can be contacted or not.
Alias
MSG_IsPostOffice(), MSG_IsPO(), MSG_IsPOAccessible(), IsPostOffice(), IsPostOfficeAccessible(),
IsPO()
Syntax
MSG_IsPostOfficeAccessible()  lSuccess
Parameters
None.
Returns
lSuccess .T. if the Post Office can be contacted; .F. if not.
Example
LOCAL nAccounts
LOCAL OldSep
LOCAL i
LOCAL szAccounts
MSG_PostOffice( "\\WALK2227\Bureau\BP.INI" )

Messaging Functions
szAccounts = MSG_GetAllAccounts()
IF ( ! EMPTY( szAccounts ) )
nAccounts = STR_numtok( szAccounts )
FOR i = 1 TO nAccounts
? "Account : " + STR_ntoken( i,szAccounts )
NEXT
ENDIF
ENDIF
MSG_LastError() : Returns a string indicating the last error in

Messaging functions.
Alias
MSG_GetLastError()
Syntax
MSG_LastError()  szError
Parameters
None.
Returns
szError message describing the last error that occurred in messaging functions.
Example
LOCAl nMessages
nMessages = MSG_count( "UNKNOWN RECIPIENT" )
IF ( nMessages == -1 )
? MSG_LastError() && "Cannot find recipient"
ENDIF
MSG_LastVersion() : Returns the file stamp of MSG functions.

Remark
Syntax
MSG_LastVersion()  szLastVersion
Parameters
None.

Messaging Functions
Returns
"C:\Focus\5.0\MSG.C-Mon Oct 19 15:55:22 1998" .
MSG_MessagesRead() : Returns the number of messages the

specified recipient has already read.
Syntax
MSG_MessagesRead( szRecipient )  nMessages
Parameters
Returns
nMessages number of messages.
MSG_MessagesReceived() : Returns the number of messages

the specified recipient has received in total.
Syntax
MSG_MessagesReceived( szRecipient )  nMessages
Parameters
Returns
MSG_MessagesSent() : Returns the number of messages a

specified originator has sent.
Syntax
MSG_MessagesSent( szOriginator )  nMessages
Parameters
szOriginator originator identification.
Returns
MSG_PO() : Gets the Post Office location.

Syntax
MSG_PO()  szPOLoc

Messaging Functions
Parameters
None.
Returns
szPOLoc current Post Office location.
Example
? MSG_PO() && "\\WALK2227\Post Office"
? MSG_POFile() && "PO.INI"
MSG_POFile() : Gets the Post Office settings file.

Syntax
MSG_POFile()  szPOFile
Parameters
None.
Returns
szFile current Post Office settings file.
Example
MSG_PostOffice() : Gets/Sets the Post office location and

settings file.
Alias
PostOffice()
Syntax
MSG_PostOffice( szPO ) szCurrentPO
Parameters
sz Post Office location and settings file. The settings file is typically an INI file.
Returns
szCurrentPO current Post office location and settings file.
Example

Messaging Functions
MSG_Read() : Reads the least recent message of a given
recipient.
Syntax
MSG_Read( szRecipient[,lDelete] )  cMessage
Parameters
lDelete should the message be deleted? By default, the message is deleted from the Post office.
Returns
szMessage the message string is composed of 6 tokens. Each token is separated by a CHR(1) . The
separator can be queried by the programmer by the MSG_GetSep() function.
Example
LOCAL szMessage
LOCAL OldSep
LOCAL szFrom
LOCAL szTo
LOCAL szDateTime
LOCAL szSubject
LOCAL szCategory
LOCAL szBody
LOCAL nTokens
szMessage = MSG_Read( "ME" )
IF ( EMPTY( szMessage ) )
? "Empty message"
ELSE
OldSep = STR_setsep( MSG_GetSep() )
nTokens = STR_numtok( szMessage )
IF ( nTokens == 6 )
szFrom = STR_ntoken( 1,szMessage )
szTo = STR_ntoken( 2,szMessage )
szDateTime = STR_ntoken( 3,szMessage )
szSubject = STR_ntoken( 4,szMessage )
szCategory = STR_ntoken( 5,szMessage )
szBody = STR_ntoken( 6,szMessage )
ELSE
? "Unexpected number of tokens"
ENDIF
ENDIF
MSG_Send() : Sends a message.

Syntax
MSG_Send( szFrom,szTo,szSubject,szCategory,szBody )  lSuccess
Parameters
szFrom sender identification.
szTo recipient identification.
szSubject subject of the message.

Messaging Functions
szCategory category of the message.
szBody body of the message.
Returns
lSuccess .T. if message was sent successfully; .F. if not.
Example
IF ( ! MSG_Send( "ME","YOU","Subject","Topic","This is my message" ) )
? "Message cannot be sent",MSG_LastError()
ENDIF
MSG_SetPONotification() : Sets a directory notification on a

specified directory.
Syntax
MSG_SetPONotification( szDir,szProc )  lSuccess
Parameters
szDir directory to monitor for messages.
szProc procedure to execute whenever a messages arrives in szDir .
Returns
lSuccess .T. if directory notification mechanism successfully hooked to szDir ; .F. if not.
Example
MSG_Successful() : Returns the string that is used to declare

Syntax
MSG_Successful()  szConstant
Parameters
None.
Returns
Example
&& Call whatever MSG function, and then simply test whether
&& MSG_LastError() is identical to MSG_Successful()

Messaging Functions
MSG_TotalMessagesSent() : Returns the total number of
messages sent through the current Post Office.
Syntax
MSG_TotalMessagesSent()  nMessages
Parameters
None.
Returns
nMessages number of messages sent.
Example
? "Average message length:",MSG_BytesSent()/MSG_TotalMessagesSent()

Math Functions
Mathematical Functions

Math Functions
MTH_atan() : Returns a Double specifying the arctangent of a

number.
Comment
The MTH_atan() function takes the ratio of two sides of a right triangle (number) and returns the corresponding
angle in radians. The ratio is the length of the side opposite the angle divided by the length of the side adjacent to the
angle.
The range of the result is -pi/2 to pi/2 radians.
To convert degrees to radians, multiply degrees by pi/180, or use DTOR() . To convert radians to degrees, multiply
radians by 180/pi or use the RTOD() function.
MTH_atan() is the inverse trigonometric function of TAN() , which takes an angle as its argument and returns the
ratio of two sides of a right triangle.
Alias
ATAN(), ATN()
Syntax
MTH_atan( x ) nRadians
Parameters
x ratio of two sides of a right triangle.
Returns
nRadians corresponding angle in radians.
MTH_combinations() : Computes the number of unordered

combinations of n on x
Comment
Combinations are computed according to the following formula: xCn = P
x n
/ n!
Syntax
MTH_combinations( x,n ) z
Parameters
x number of choices.
n series of n unordered choices.
Returns
z number of combinations = xPn = x! / (x-n)! The Lotto (or Loto) is a good candidate for the
number of different solutions. If you have 42 balls in total, and you need to get 6 out of that,
then the number of solutions is 42C6 = 42P6 / 6! … which makes 5245786 .

Math Functions
See also
MTH_permutations()
C Code
double FWFactorial( int x )
/*-----------------------*/
{
double y=1;
x = abs( x );
while ( x > 1 )
{
y *= (double) x--;
}
return ( y );
}
FOCUSFNC FW_MTH_factorielle( XBASE_PARAMETERS )

/*-------------------------------------------*/
{
_retnd( (double) FWFactorial( _parni(1) ) );
FOCUSFNCRETURN();
}
double FWPermutations( int x,int n )

/*---------------------------------*/
{
// xPn = number of permutations possible
// on x numbers taken by series of n
// ordered numbers
//
// Example: 14!
// 14P4 = _______ = 14 * 13 * 12 * 11
// (14-4)!
double result;
int i=1;
x = abs( x );
n = abs( n );
result = (double) x;
while ( i++ < n )

{
result *= (double) --x;
}
return( result );
}
FOCUSFNC FW_MTH_permutations( XBASE_PARAMETERS )

/*--------------------------------------------*/
{
_retnd( (double) FWPermutations( _parni(1),_parni(2) ) );
FOCUSFNCRETURN();
}
double FWCombinations( int x,int n )

/*--------------------------------*/
{
// xCn = number of combinations possible
// on x numbers taken by series of n
// unordered numbers
//
// Example: 14P4 14 * 13 * 12 * 11
// 14C4 = ______ = ------------------
// (4)! 4 * 3 * 2 * 1
//
return ( (double) ( FWPermutations( x,n ) / FWFactorial( n ) ) );

}

Math Functions
FOCUSFNC FW_MTH_combinations( XBASE_PARAMETERS )
/*--------------------------------------------*/
{
_retnd( (double) FWCombinations( _parni(1),_parni(2) ) );

FOCUSFNCRETURN();
}
MTH_distance() : computes the distance between 2 points

Comment
The calculations are based upon the following formula :
Distance = ((x 2-x1)2 + (y2-y1)2)
Syntax
MTH_distance( x1,y1,x2,y2 ) nDistance
Parameters
x1 x position (left).
y1 y position (top).
x2 x position (left).
y2 y position (top).
Returns
nDistance distance between (x1,y1) and (x2,y2).
MTH_LastVersion() : Returns the file stamp of MTH functions.

Remark
Syntax
MTH_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\FWMATH.C-Mon Oct 19 15:55:22 1998" .

Math Functions
MTH_origin() : détermine l'origine à l'ordonnée d'une droite
passant par deux points.
Comment
y = ax + b
We here try to determine the b parameter.
Syntax
MTH_origin( x1,y1,x2,y2 ) nOrigin
Parameters
x1 abscisse du premier point.
y1 ordonnée du premier point.
x2 abscisse du deuxième point.
y2 ordonnée du deuxième point.
Returns
origin Ordonnée à l'origine.
MTH_pente() : détermine la pente d'une droite passant par

deux points.
Comment
y = ax + b
We here try to determine the a parameter.
Syntax
MTH_pente( x1,y1,x2,y2 ) pente
Parameters
x1 abscisse du premier point.
y1 ordonnée du premier point.
x2 abscisse du deuxième point.
y2 ordonnée du deuxième point.
Returns
pente pente de la droite. Si une droite ne varie pas en abscisse ainsi que l'illustre la capture d'écran
qui suit, alors la valeur retournée par MTH_pente() devrait représenter l'infini ().

Math Functions
MTH_permutations() : Computes the number of ordered

permutations of n on x
Comment
Permutations are computed according to the following formula: xPn = x! / (x-n)!
Syntax
MTH_permutations( x,n ) z
Parameters
x number of choices.
n series of n ordered choices.
Returns
z number of permutations = xPn = x! / (x-n)!
See also
MTH_combinations()

Network Functions
Network Functions

Network Functions
NET_CancelConnection() : Breaks an existing network

connection.
Syntax
NET_CancelConnection( szRes[,lForce] )  lSuccess
Parameters
szRes local name.
lForce forcing disconnection. Optional parameter. By default, lForce is set to .F..
Returns
lSuccess .T. is the function succeeds; .F. otherwise.
Example
&& Disconnect network resource; force disconnection even if there are open
&& files or jobs on the connection.
? NET_CancelConnection( "K:",.T. )
See also
NET_CancelConnection()
NET_ConnectionDialog() : Presents a dialog box to establish a

new network connection.
Syntax
NET_ConnectionDialog( [nType] )  lSuccess.
Parameters
nType 1 for disks resources (default); 2 for print resources.
Returns
lSuccess .T. if the function is successful; .F. otherwise.
Example
IF ( ! NET_ConnectionDialog() )
? "Error:",NET_LastError()
ENDIF
The Connection Dialog Box (Windows 95)

Network Functions
The Connection Dialog Box (Windows NT)
See also
NET_DisconnectDialog()
NET_DisconnectDialog() : Presents a dialog box to cancel a

network connection.
Syntax
NET_DisconnectDialog()  lSuccess
Parameters
None.
Returns
Example
NET_DisconnectDialog()
The Disconnect Dialog Box (Windows 95)

Network Functions
The Disconnect Dialog Box (Windows NT)
See also
NET_ConnectionDialog()
NET_EnumConnections() : Enumerates the network

connections.
Syntax
NET_EnumConnections()  szConnections
Parameters
None.
Returns
szConnections a tokenized string indicating all the connections. The string is formatted in such a way that the
local resource is mentioned first, then a caret ( "^") is placed, and finally the remote resource is
mentioned. Multiple connections are separated by a ";" . For example the following string
denotes 2 connections :
F:^\\BEIPT15\F;G:^\\WALK2227\BUREAU , F: is mapped to \\BEIPT15\F and G: is

mapped to \\WALK2227\BUREAU .
NET_EthernetAddress() : Obtains the Ethernet address of the

network card.
Remark
The NetBIOS layer has to be active. The Ethernet address is formed out of 6 numbers.
Syntax
NET_EthernetAddress( [n] )  nAddress|szAddress
Parameters
n the address to obtain. Optional parameter. If passed n must be >= 1 and <= 6. When not
passed, the full Ethernet Address is returned as a character string.
Returns
nAddress the desired address. –1 is returned when the Ethernet Address can’t be determined.
szAddress the full Ethernet address is returned when the n parameter is not passed to the function.

Network Functions
Example
LOCAL szAddress
szAddress = PADL( NUM_hexa( NET_EthernetAddress(1) ),3,"0" ) + "." + ;

PADL( NUM_hexa( NET_EthernetAddress(2) ),3,"0" ) + "." + ;
PADL( NUM_hexa( NET_EthernetAddress(6) ),3,"0" ) + ;
NET_GetComputerName() : Retrieves the computer name of

the current system.
Syntax
NET_GetComputerName()  szComputer
Parameters
None.
Returns
szComputer computer name. This name is established at system startup, when it is initialized from the
registry. If function was unsuccessful, it simply returns an empty string ( "").
NET_GetHostName() : Returns the standard host name for the

local machine.
Syntax
NET_GetHostName()  szHost
Parameters
None.
Returns
szHost standard host name.
NET_GetUserName() : Returns the user name attached to the

local machine.
Remark
The function can be very useful for logon processes.
Syntax
NET_GetUserName()  szUser
Parameters
None.
Returns
szUser user name.

Network Functions
Example
? NET_GetUsername() && "Pat Boens"
NET_InternetTime() : Returns the Atomic clock date/time with

1sec accuracy.
Remark
The function can be very useful for synchronizing machines of a network.
Syntax
NET_InternetTime( [szHost] )  iUTC
Parameters
szHost optional host. By default, the internal host used by FOCUS.FLL is "time.nrc.ca" . The
following hosts implement Time protocol on the Internet:
time-a.nist.gov
time-b.nist.gov
time-a.timefreq.bldrdoc.gov
time-b.timefreq.bldrdoc.gov
time-c.timefreq.bldrdoc.gov
utcnist.Colorado.edu
time.nist.gov
time-nw.nist.gov
nist1.datum.com
nist.dc.glassey.com
nist.ny.glassey.com
nist.sj.glassey.com
nist1.aol-ca.truetime.com
nist1.aol-va.truetime.com
Returns
iUTC UTC time as integer.
Example
? TIM_CTime( NET_InternetTime( "time-nw.nist.gov" ) ) && Sun Mar 10 20:31:23 2002
NET_LastError() : Last error encountered in NET functions.

Syntax
NET_LastError()  szLastError
Parameters
None.
Returns
szLastError last error that occurred while using the NET_*() functions.
Example
nEthernetID = NET_EthernetAddress(1)
? NET_LastError() && "The operation completed successfully."
nEthernetID = NET_EthernetAddress(-1)
? NET_LastError() && "Invalid parameter"

Network Functions
NET_LastVersion() : Returns the file stamp of NET functions.
Remark
Syntax
NET_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\NET.C-Mon Oct 19 15:55:22 1998" .
NET_level() : Sets up the user level.

Syntax
NET_level( nLevel )  nOldLevel
Parameters
nLevel user level.
Returns
nOldLevel previous user level.
NET_max() : Maximum number of software users that can log

in simultaneously.
Syntax
NET_max( <nUsers> )  nOldUsers
Parameters
nUsers number of users that can log simultaneously into your application.
Returns
nOldUsers previous number of users.
NET_mode() :?????????
Special
Not ready yet.

Network Functions
Syntax
NET_mode( nMode )  nOldMode
Parameters
nMode ????????
Returns
nOldMode ???????.
NET_proc() : Customizes the command to be executed by

dedicated network timer.
Syntax
NET_proc( szCommand )  .T.
Parameters
szCommand FoxPro command.
Returns
NET_SetComputerName() : Sets the computer name to be

used the next time the system is restarted.
Syntax
NET_SetComputerName( szName )  lSuccess
Parameters
szName computer name.
Windows 95 : If this string contains one or more characters that are outside the standard
character set, those characters are coerced into standard characters.
Windows NT : If this string contains one or more characters that are outside the standard
character set, NET_SetComputerName() returns .F. . It does not coerce the characters
outside the standard set.
The standard character set includes letters, numbers, and the following symbols : ! @ # $ %
^ & ' ) ( . - _ { } ~ .
Returns
lSuccess .T.. if function was successful, .F. if not.
Example
OldName = NET_GetComputerName()
? NET_SetComputerName( "PAT78" )
? NET_SetComputerName( OldName )

Network Functions
After changing the Computer Name (Windows 95)
NET_setnet() : Must the network be setting up.

Syntax
NET_setnet( <lStatus> )  lOldStatus
Parameters
lStatus .T. indicates that FOCUS should take care of network settings; .F. otherwise.
Returns
lOldStatus previous status of the network flag.
NET_timset() : Sets a timer dedicated to network attention.

Syntax
NET_timset( <nTimeInterval> )  nNetTimer
Parameters
nTimeInterval time interval in milliseconds.
Returns
nNetTimer time identifier.
NET_timkil() : Kills the dedicated network timer.

Syntax
NET_timkil( <nNetTimer> )  .T.

Network Functions
Parameters
nNetTimer timer identifier.
Returns
NET_timkil() : Kills the dedicated network timer.NET_userno() :

User number.
Syntax
NET_userno( <nUserNo> )  nOldUserNo
Parameters
nUserNo most recently logged user number.
Returns
nOldUserNo previous most recently logged user number.

Notification Functions

Functions Synopsis
File (or Directory) Notification functions are handy possibilities of FOCUS. Imagine being kept informed whenever there
is a change in a directory. That's what the Notification Functions are all about in fact.
These functions request that the operating system signal a change notification handle whenever it detects an
appropriate change.
To track these changes, FOCUS.FLL uses an internal timer whose frequency is set to 5000 milliseconds. The frequency
can be freely adjusted.
Usually, the Notification functions are used in the following sequence :
1. NOT_set()
2. <in between, FOCUS.FLL will call a procedure that you passed to NOT_set() whenever
there is a change such as the ones you want to track down>
3. NOT_kill()

NOT_Frequency() : Adjusts the frequency of the internal timer

of FOCUS.FLL.
Syntax
NOT_Frequency( [nMilliSeconds] )  nOldFrequency
Parameters
nMilliSeconds number of milliseconds used by the internal timer of FOCUS. Any change to the directories to
monitor will be reported within that number of milliseconds. This parameter is optional; if it's
not passed, the function simply returns the current frequency.
When setting up a new frequency, the internal timer of FOCUS is re-activated.
Returns
nOldFrequency current frequency.
Example
LOCAL nHandle
IF ( NOT_HandlesFree() > 0 )
NOT_Frequency( 1000 ) && Any change will be reported within 1 sec
nHandle = NOT_set( "C:\","WarnMe",.T.,24 )
MESSAGEBOX( "Notification set successfully",64,"Notification" )
ELSE
MESSAGEBOX( "Cannot set notification",48,"Notification" )
ENDIF
ELSE
MESSAGEBOX( "Cannot set notification. Free up some handles.",48,"Notification" )
ENDIF
PROCEDURE WarnMe( nHandle )

MESSAGEBOX( "Somebody touched my C drive",64,"Notification" )
RETURN
NOT_HandlesCount() : Returns the maximum number of

notification handles.
Syntax
NOT_HandlesCount()  nHandles
Parameters
None.
Returns
nHandles maximum number of notification handles.
NOT_HandlesFree() : Returns the number of free notification

handles.
Syntax
NOT_HandlesFree()  nHandles

Parameters
None.
Returns
nHandles number of free handles.
Example
LOCAL nHandle
ELSE
ENDIF
ELSE
ENDIF

RETURN
NOT_info() : Returns notification information.

Syntax
NOT_Info( nHandle,nInfo )  szInfo|lInfo|nInfo
Parameters
nHandle handle identifying the notification to be queried. Be careful to pass a handle whose value is
comprised between NOT_MinHandle() and NOT_MaxHandle() ; otherwise illegal operations
can appear.
nInfo information type to query.
VALUE DESCRIPTION
1 Directory to monitor
2 Associated procedure
3 Subdir
4 Flags
5 Suspended
6 Strategy
7 Cargo member
Returns
szInfo either the directory name or the trigger procedure.
lInfo suspended status : .F. = Notification still active
.T. = Notification suspended
nInfo flags.
Example
LOCAL nHandle

NOT_Frequency( 1000 ) && Any change will be reported within 1 sec
? NOT_info( nHandle,1 ) && "C:\"
? NOT_info( nHandle,2 ) && "WarnMe"
? NOT_info( nHandle,3 ) && .T.
? NOT_info( nHandle,4 ) && 24
ELSE
ENDIF
ELSE
ENDIF

RETURN
NOT_IsTimer() : Is the internal timer of FOCUS.FLL active?

Syntax
NOT_IsTimer()  lTimer
Parameters
None.
Returns
lTimer .T. internal timer of FOCUS is alive; .F. if not.
Example
? NOT_Frequency( 1000 ) && This statement forces the timer to be active
? NOT_IsTimer() && .T.
? NOT_KillTimer() && Kill the internal timer
? NOT_IsTimer() && .F.
NOT_Kill() : Kills a notification.

Alias
NOT_Close()
Syntax
NOT_Kill( nHandle )  lSuccess
Parameters
nHandle handle identifying the notification to be killed.
Returns
lSuccess .T. indicates that the notification was killed successfully; .F. otherwise. All notification
handles set by an application should be killed; otherwise they all remain in force. When the SET
LIBRARY TO statement is issued, unloading FOCUS.FLL from memory, FOCUS releases all
notifications automatically.

Example
PROCEDURE EndOfProgram()
NOT_Kill( nHandle )
RETURN
NOT_KillTimer() : Kills the internal timer of FOCUS.FLL.

Syntax
NOT_KillTimer()  .T.
Parameters
None.
Returns
.T. the function always returns .T. . The internal timer of FOCUS.FLL can be re-established with
the NOT_Frequency() function.
Example
? NOT_KillTimer() && Kill the internal timer
? NOT_IsTimer() && .F.
NOT_LastError() : Returns an error string indicating the nature

of the last error encountered.
Alias
NOT_GetLastError()
Syntax
NOT_LastError()  szErrorString
Parameters
None.
Returns
szErrorString last error string.
Example
LOCAL nDummyHandle
nDummyHandle = NOT_set( "DoesNotExist","",.F.,24 )
IF ( nDummyHandle == -1 )
? NOT_LastError() && "The system cannot find the file specified."
ENDIF

NOT_LastVersion() : Returns the file stamp of NOT functions.
Remark
Syntax
NOT_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\NOTIFICATIONS.C-Mon Oct 19 15:55:22 1998" .
NOT_MaxHandle() : Returns the highest possible notification

handle.
Syntax
NOT_MaxHandle()  nHandle
Parameters
None.
Returns
nHandle highest potential handle.
NOT_MinHandle() : Returns the lowest possible notification

handle.
Syntax
NOT_MinHandle()  nHandle
Parameters
None.
Returns
nHandle lowest potential handle.

NOT_RestoreAll() : Restores all notifications saved with
NOT_SaveAll().
Syntax
NOT_RestoreAll( szAll )  lSuccess
Parameters
szAll a character string that represents all the notifications set. This character string is usually set by
a previous call to NOT_SaveAll() .
Returns
Example
LOCAL szAll
szAll = NOT_SaveAll()
NOT_Zapll()
IF ( ! NOT_RestoreAll( szAll ) )
? "Cannot reset all notifications"
ENDIF
NOT_Resume() : Resumes a notification.

Syntax
NOT_Resume( nHandle )  .T.
Parameters
nHandle handle identifying the notification to be resumed. Be careful to pass a handle whose value is
comprised between 0 and 49; otherwise illegal operations can appear.
Returns
Example
LOCAL nHandle
ELSE
ENDIF

LOCAL nLogFile
NOT_Suspend( nHandle )
nLogFile = FCREATE( "C:\LOGFILE" )
IF ( nLogFile != -1 )
FPUTS( "Somebody touched my C drive (" + TTOC( DATETIME() ) + ")" )
FCLOSE( nLogFile )
ENDIF

NOT_Resume( nHandle )
RETURN
NOT_ResumeAll() : Resumes all notifications.

Syntax
NOT_Resume()  .T.
Parameters
None.
Returns
Example
LOCAL nHandle
ELSE
ENDIF

LOCAL nLogFile
NOT_SuspendAll()
nLogFile = FCREATE( "C:\LOGFILE" )
FCLOSE( nLogFile )
ENDIF
NOT_ResumeAll()
RETURN
NOT_SaveAll() : Saves all notifications in a character string.

Syntax
NOT_SaveAll()  szAll
Parameters
None.
Returns
szAll a character string that represents all the notifications set.
Example
LOCAL szAll
NOT_ZapAll()
ENDIF
NOT_Set() : Sets a notification.

Syntax
NOT_Set( szDir,szProc,lSubDir,nFlags )  nHandle
Parameters
szDir directory to monitor.
szProc procedure to execute whenever a change is detected. Only the name of the procedure should
be mentioned. This procedure is passed a parameter: the handle that caused the procedure to
be called.
lSubDir should FOCUS also monitor sub-directories?
nFlags changes filter. It can be one of the following values:
Value Meaning
FILE_NOTIFY_CHANGE_FILE_NAME Any filename change in the watched directory or subtree
0x00000001
causes a change notification wait operation to return.
Changes include renaming, creating, or deleting a filename.
FILE_NOTIFY_CHANGE_DIR_NAME Any directory-name change in the watched directory or
0x00000002
subtree causes a change notification wait operation to return.
Changes include creating or deleting a directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES Any attribute change in the watched directory or subtree
0x00000004
causes a change notification wait operation to return
FILE_NOTIFY_CHANGE_SIZE Any file-size change in the watched directory or subtree
0x00000008
causes a change notification wait operation to return. The
operating system detects a change in file size only when the
file is written to the disk. For operating systems that use
extensive caching, detection occurs only when the cache is
sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE Any change to the last write-time of files in the watched
0x00000010
directory or subtree causes a change notification wait
operation to return. The operating system detects a change
to the last write-time only when the file is written to the disk.
For operating systems that use extensive caching, detection
occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_ACCESS
0x00000020
FILE_NOTIFY_CHANGE_CREATION
0x00000040
FILE_NOTIFY_CHANGE_SECURITY Any security-descriptor change in the watched directory or

0x00000100
subtree causes a change notification wait operation to return.
Returns
nHandle notification handle or –1 if the function is not successful. 50 notifications can be set in total.
Example
LOCAL nHandle
ELSE
ENDIF

RETURN
NOT_Strategy() : Establishes the strategy used to respond to

directory notification.
Syntax
NOT_Strategy( nHandle,nNewStrategy )  nStrategy
Parameters
nHandle handle identifying the notification to be suspended. Be careful to pass a handle whose value is
nNewStrategy strategy to apply : 1 = FoxPro function to launch; 2 = program to launch.
Returns
nStrategy strategy in use before entering the function.
Example
LOCAL nHandle
&& This means that WarnMe is a program (EXE) that should be
&& launched and it should receive one parameter (the handle
&& of the notification mechanism)
NOT_Strategy( nHandle,2 )
ELSE
ENDIF
NOT_Successful() : Returns the string that is used to declare

Syntax
NOT_Successful()  szConstant
Parameters
None.
Returns
Example
&& Call whatever NOT function, and then simply test whether
&& NOT_LastError() is identical to NOT_Successful()
NOT_Suspend() : Suspends a notification.

Syntax
NOT_Suspend( nHandle )  .T.

Parameters
nHandle handle identifying the notification to be suspended. Be careful to pass a handle whose value is
On some circumstances, you might temporarily stop notifications, especially when you will
trigger a notification change within the procedure that handles notification changes. That's why
the NOT_Suspend() function is provided.
A notification that has been stopped can be resumed with NOT_Resume() .
Returns
Example
LOCAL nHandle
ELSE
ENDIF

LOCAL nLogFile
NOT_Suspend( nHandle )
nLogFile = FCREATE( "C:\LOGFILE.LOG" )
FCLOSE( nLogFile )
ENDIF
NOT_Resume( nHandle )
RETURN
NOT_SuspendAll() : Suspends all notifications.

Syntax
NOT_SuspendAll()  .T.
Parameters
None.
Returns
Example
LOCAL nHandle
ELSE
ENDIF

LOCAL nLogFile

NOT_SuspendAll()
nLogFile = FCREATE( "C:\LOGFILE.LOG" )
FCLOSE( nLogFile )
ENDIF
NOT_ResumeAll()
RETURN
NOT_ZapAll() : Discards all notifications.

Syntax
NOT_ZapAll()  .T.
Parameters
None.
Returns
Example
LOCAL szAll
NOT_ZapAll()
ENDIF

NTEvents Functions
NTEvents Functions

NTEvents Functions
Functions Synopsis
Many applications record errors and events in various proprietary error logs. These proprietary error logs have
different formats and display different user interfaces. Moreover, you cannot merge the data to provide a complete
report. Therefore, you need to check a variety of sources to diagnose problems. Event logging in Microsoft® Windows
NT®/Windows® 2000 provides a standard, centralized way for applications (and the operating system) to record
important software and hardware events. The event-logging service stores events from various sources in a single
collection called an event log. Windows NT/Windows 2000 also supplies Event Viewer for viewing the logs, and a
programming interface for examining the logs.
The NTE_*() functions of FOCUS.FLL are especially useful to directly interface with the standard services of Windows
NT/Windows 2000.
Event Types3
There are 5 types of events. All event classifications have well-defined common data and can optionally include
event-specific data. The application indicates the event type when it reports an event. Each event must be of a
single type. The Windows NT/Windows 2000 Event Viewer uses this type to determine which icon to display in the
list view of the log.
The following table describes the event types used in event logging.
Event type Description

Information Information events indicate infrequent but significant successful operations.
Warning Warning events indicate problems that are not immediately significant, but that may
indicate conditions that could cause future problems. Resource consumption is a good
candidate for a warning event. For example, an application can log a warning event if
disk space is low.
Error Error events indicate significant problems that the user should know about. Error
events usually indicate a loss of functionality or data.
Success audit Success audit events are security events that occur when an audited access attempt
is successful. For example, a successful logon attempt is a success audit event.
Failure audit Failure audit events are security events that occur when an audited access attempt
fails. For example, a failed attempt to open a file is a failure audit event.
Logging Guidelines
Event logs store records of significant events on behalf of Windows NT/Windows 2000 and applications running
on Windows NT/Windows 2000. Because the logging functions are general purpose, you must decide what
information is appropriate to log. Generally, you should log only information that could be useful in diagnosing a
hardware or software problem. Event logging is not intended to be used as a tracing tool4.
Choosing Events to Log

The following are examples of cases in which event logging can be helpful:
Resource problems. If an application gets into a low-memory situation (caused by a code bug or inadequate
memory) that degrades performance, logging a warning event when memory allocation fails might provide a
clue about what went wrong.
Hardware problems. If a device driver encounters a disk controller time-out, a power failure in a parallel port, or
a data error from a network or serial card, logging information about these events can help the system
administrator diagnose hardware problems. The device driver logs the error.
3
Extracted from Microsoft documentation and provided here for the sake of simplicity.
4
FOCUS.FLL provides additional functions for tracing tools (LOG_*() and TRA_*()).

NTEvents Functions
Bad sectors. If a disk driver encounters a bad sector, it may be able to read from or write to the sector after
retrying the operation, but the sector will go bad eventually. Therefore, if the disk driver can proceed, it should
log a warning; otherwise, it should log an error event. If a file system driver finds a large number of bad
sectors, fixes them, and logs warning events, logging information of this type might indicate that the disk is
about to fail.
Information events. A server application (such as a database server) records a user logging on, opening a
database, or starting a file transfer. The server can also log error events it encounters (cannot access file, host
process disconnected, and so on), a corruption in the database, or whether a file transfer was successful.
Logfiles
Applications and services use the Application logfile. Device drivers use the System logfile. The system will
generate success and failure audit events in the Security log when auditing is turned on.
<TO BE CONTINUED>
How To Work With the NTE_*() Functions of FOCUS.FLL?

NTE_*() functions bear resemblance with File functions in the sense that before acting on an Event Log, you first
need to open it. What the function returns is a handle to the log. Further on, you pass this handle as a parameter to
additional NTE_*() functions.

NTEvents Functions
NTE_ClearEventLog() : Clears a given event log.

Syntax
NTE_ClearEventLog( hLog[,szBackupFile] )  lSuccess
Parameters
hLog Handle to the event log to be cleared.
szBackupFile Optional parameter. The name of an optional backup file before the event log is cleared.
Returns
Example
LOCAL hLog
LOCAL szBackup
m.hLog = NTE_OpenEventLog( NET_GetComputerName(),"Application" )
IF ( m.hLog != -1 )
m.szBackup = "D:\APPLICATION.NTLOG"
IF ( NTE_ClearEventLog( m.hLog,m.szBackup ) )
? "The application log has been cleared successfully"
ELSE
? "The application log could not be cleared"
ENDIF
NTE_CloseEventLog( m.hLog )
ENDIF
NTE_CloseEventLog() : Closes a read handle to the specified

event log.
Syntax
NTE_CloseEventLog( hLog )  lSuccess
Parameters
hLog Handle to the event log to be closed.
Returns
Example
LOCAL hLog
LOCAL szBackup
IF ( m.hLog != -1 )
ELSE
ENDIF

NTEvents Functions
ENDIF
NTE_OpenEventLog() : Opens an event log.

Syntax
NTE_OpenEventLog( szComputerName,szType )  hLog
Parameters
szComputerName Name of the computer (usually the name of the machine the application runs on).
szType Name of the log to open ("Application" , "Security" ," System" ).
Returns
hLog Handle to the given application log or -1 if the function failed.
Example
LOCAL hLog
LOCAL szBackup
IF ( m.hLog != -1 )
ELSE
ENDIF
ENDIF

Numeric Functions
Numeric Functions

Numeric Functions
NUM_Base() : Converts the digits of a given integer argument

to a string, by taking into account a given radix.
Syntax
NUM_Base( n,nRadix )  szNum
Parameters
n the integer number to transform.
nRadix the radix to take into account. Must be in the range 2 – 36.
Returns
szNum the string corresponding to the transformation of n in radix nRadix .
Example
? NUM_base( 3, 2 ) && "11"
? NUM_base( 10,16 ) && "a"
? NUM_base( 32,16 ) && "20"
? NUM_base( 7, 8 ) && "7"
? NUM_base( 9, 8 ) && "11"
? NUM_radix( NUM_base( 5000,36 ),36 ) && 5000
See also
NUM_radix() .
NUM_between() : Determines if a number is between 2 others.

Syntax
NUM_between( n,nLow,nHight )  lBetween
Parameters
n number to test.
nLow low value of range.
nHigh high value of range.
Returns
lBetween .T. if n >= nLow and n <= nHigh; .F. otherwise
Example
? NUM_Between( 10,7,20 ) && .T.
? NUM_Between( 10,15,20 ) && .F.
NUM_BinHi() : Returns the high byte value of a number.

Syntax
NUM_BinHi( n )  nHigh

Numeric Functions
Parameters
n number to process.
Returns
nHigh high byte of n.
Example
? NUM_BinHi( 255 ) && 0
? NUM_BinHi( 256 ) && 1
? NUM_BinHi( 257 ) && 1
? NUM_BinHi( 512 ) && 2
? NUM_BinHi( 7894 ) && 30
See also
NUM_BinLow() .
NUM_BinLow() : Returns the low byte value of a number.

Syntax
NUM_BinLow( n )  nLow
Parameters
Returns
nLow low byte of n.
Example
? NUM_BinLow( 255 ) && 255
? NUM_BinLow( 256 ) && 0
? NUM_BinLow( 257 ) && 1
? NUM_BinLow( 512 ) && 0
? NUM_BinLow( 7894 ) && 214
? NUM_BinLow( 7894 ) == 7894 % 256 && .T.
See also
NUM_BinHi() .
NUM_gcd() : Euclid's implementation of the greatest common

divisor of two integers.
Syntax
NUM_gcd( n1,n2] )  n
Parameters
n1 integer #1.
n2 integer #2.

Numeric Functions
Returns
n the greatest common divisor.
Example
? NUM_gcd( 6, 9 ) && 3
? NUM_gcd( 6, 6 ) && 6
? NUM_gcd( 6,78 ) && 6
? NUM_gcd( 6,77 ) && 1
? NUM_gcd( 3,15 ) && 3
? NUM_gcd( 4,15 ) && 1
? NUM_gcd( 5,15 ) && 5
NUM_GetNextPrime() : Get the next prime number.

Syntax
NUM_GetNextPrime( n )  nNext
Parameters
n the integer from which to obtain the next prime number.
Returns
nNext next prime number.
Example
? NUM_IsPrime( 101 ) && .T.
? NUM_GetNextPrime( 103 ) && 107
? NUM_GetPrevPrime( 5741 ) && 5737
See also
NUM_IsPrime() , NUM_GetPrevPrime() .
NUM_GetPrevPrime() : Get the previous prime number.

Syntax
NUM_GetPrevPrime( n )  nPrevious
Parameters
n the integer from which to obtain the previous prime number.
Returns
nPrevious previous prime number.
Example

Numeric Functions
See also
NUM_IsPrime() , NUM_GetPrevPrime() .
NUM_hexa() : Hexadecimal equivalent of an integer.

Syntax
NUM_hexa( n )  szHexa
Parameters
Returns
szHexa hexadecimal equivalent of n.
Example
? NUM_hexa( 255 ) && "FF"
? rgb2hexa( 247,241,226 ) && "#F7F1E2"
FUNCTION rgb2hexa( a,b,c )

RETURN ( "#" + PADL(NUM_hexa(a),2,"0")+PADL(NUM_hexa(b),2,"0")+PADL(NUM_hexa(c),2,"0") )
See also
STR_hexa() , STR_htos() , NUM_htoi()
NUM_htoi() : Integer equivalent of an hexadecimal number.

Syntax
NUM_htoi( szHexa )  n
Parameters
szHexa hexadecimal number to process.
Returns
n integer which is the equivalent of the hexadecimal string.
Example
? NUM_hexa( 255 ) && "FF"
? NUM_htoi( "FF" ) && 255
See also
NUM_InitRandom() : Initializes internal buffers and values for

random numbers generation.
Comment
There is no absolute need to call the NUM_InitRandom() function before using NUM_RandomInt() or
NUM_RandomDouble() . When FOCUS.FLL loads, it automatically calls this function to cause proper initialization.
However, the developer might decide to re-initialize all internals. That's what this function is all about.
Numeric Functions
Syntax
NUM_InitRandom( [nInteger] )  .T.
Parameters
nInteger seed. Optional parameter. If the seed number is not passed, the NUM_InitRandom() function
uses the current time of the PC.
Returns
See also
NUM_RandomInt() , NUM_RandomDouble() ,
NUM_int_max() : Get the highest value of an integer.

Syntax
NUM_int_max()  n
Parameters
None.
Returns
n maximum value of an integer.
Example
? NUM_int_max() && 2147483647
See also
NUM_int_min()
NUM_int_min() : Get the lowest value of an integer.

Syntax
NUM_int_min()  n
Parameters
None.
Returns
n minimum value of an integer.
Example
? NUM_int_min() && -2147483648
See also
NUM_int_max()

Numeric Functions
NUM_IsPrime() : Is a number a prime number?
Syntax
NUM_IsPrime( n )  lPrime
Parameters
n the integer to test.
Returns
lPrime .T. if n is a prime number; .F. if not.
Example
See also
NUM_GetNextPrime() , NUM_GetPrevPrime() .
NUM_LastVersion() : Returns the file stamp of NUM functions.

Remark
Syntax
NUM_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\NUM.C-Mon Oct 19 15:55:22 1998" .
NUM_long_max() : Get the highest value of a long.

Remark
Under Windows, a long is equivalent to an integer. Therefore, NUM_int_max() and NUM_long_max() return the
same value.
Syntax
NUM_long_max()  n

Numeric Functions
Parameters
None.
Returns
n maximum value of a long.
Example
? NUM_long_max() && 2147483647
See also
NUM_long_min()
NUM_long_min() : Get the lowest value of a long.

Remark
Under Windows, a long is equivalent to an integer. Therefore, NUM_int_min() and NUM_long_min() return the
same value.
Syntax
NUM_long_min()  n
Parameters
None.
Returns
n minimum value of a long.
Example
? NUM_long_min() && -2147483648
See also
NUM_int_max()
NUM_octal() : Octal equivalent to an integer number.

Syntax
NUM_octal( nInteger )  szOctal
Parameters
nInteger integer to process.
Returns
szOctal octal representation.
Example
? NUM_octal( 8 ) && "10"
? NUM_octal( 10 ) && "12"

Numeric Functions
? NUM_octal( 20 ) && "24"
See also
NUM_Radix() : Reverse function of NUM_Base().

Syntax
NUM_Radix( szNum,nRadix )  n
Parameters
szNum the string to transform to a number.
nRadix the radix to take into account. Must be in the range 2 – 36.
Returns
n the resulting integer number.
Example
? NUM_base( 3, 2 ) && "11"
? NUM_base( 10,16 ) && "a"
? NUM_base( 32,16 ) && "20"
? NUM_base( 7, 8 ) && "7"
? NUM_base( 9, 8 ) && "11"
? NUM_radix( NUM_base( 5000,36 ),36 ) && 5000
See also
NUM_Base() .
NUM_RandomDouble() : Generates a random float in the range

0 to 1.
Syntax
NUM_RandomDouble( )  nNum
Parameters
None.
Returns
nNum random float number.
Example
? NUM_RandomDouble() && 0,9304951553
See also
NUM_InitRandom() , NUM_RandomInt() .

Numeric Functions
NUM_RandomInt() : Generates a random integer.
Syntax
NUM_RandomInt()  nInt
Parameters
None.
Returns
nInt Random integer.
See also
NUM_InitRandom() , NUM_RandomDouble() .
NUM_UniversalID() : Generates a unique identifier that is

supposed to be unique in space and unique in time.
Caution
The algorithm that was chosen in the current implementation uses network identifiers to generate the
universal ID. Therefore, an Ethernet adapter MUST be present in the machine AND the NetBIOS layer MUST
be activated. Otherwise, the function can return unpredictable results.
Remark
The algorithm uses:
 the Ethernet adapter unique identifier
 the current IP address
 the current time
 the tick count passed before last boot
 and counters to circumvent consecutive calls
With it, it is capable to generate a global ID that is said to be unique in space and unique in time.
Syntax
NUM_UniversalID()  szID
Parameters
None.
Returns
szID a globally unique ID that can be used in distributed environments. Very handy for keys that are
generated for primary keys in tables for example. The ID can be up to 66 bytes long.

Numeric Functions
Example
? NUM_UniversalID() && "010305AC4D3E21709300C0A88EA527C0A8FE477F00100002"
? NUM_UniversalID() && "030307FB8C3E21712B00C0A88EA527C0A8FE477F00100005"
? NUM_UniversalID() && "05030841DC3E21713D00C0A88EA527C0A8FE477F00100009"
? NUM_UniversalID() && "07030854D83E21714200C0A88EA527C0A8FE477F0010000D"

Object Functions
Object Oriented Functions

Object Functions
OBJ_AddProperty() : Adds a property to an object at Run-Time.

Syntax
OBJ_AddProperty( oObject,szProperty,xValue )  lSuccess
Parameters
oObject the object to add the property to.
szProperty the name of the property to add.
xValue the value to assign the property to.
Returns
lSuccess .T. if the property was successfully added; .F. if not.
Example
LOCAL oForm
oForm = CREATEOBJECT( "Form" )
IF ( TYPE( "oForm" ) == "O" .AND. ! ISNULL( oForm ) )

OBJ_AddProperty( oForm,"Myproperty","My value" )
ENDIF
OBJ_LastVersion() : Returns the file stamp of OBJ functions.

Remark
Syntax
OBJ_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\OBJECTS.C-Mon Oct 19 15:55:22 1998" .

Printer Functions
Printer Functions

Printer Functions
Functions Synopsis
Enumerating the Available Printers
Obtaining all the available printers can be achieved by following several strategies. One might want to obtain the list of
installed printers from Windows INI files; another one would choose one registry place; a third one would disagree and
propose another registry location; yet exists the EnumPrinters() Win32 API call! .. or simply the APRINTERS()
native VFP function.
The latter has our favor because it is available from Windows NT 3.51 and exists for Win95, Win98 and Windows Me …
and of course, because we totally control its code which makes it very attractive to us!
The latter has our favor because it is available since Windows NT 3.51 and exists for Win95, Win98 and Windows Me.
This API call has been wrapped in FOCUS.FLL through the PRN_EnumPrinters() function. What this function does
is pretty simple: it returns a tokenized string of Printer names with each printer separated with a caret ( ^):

Printer Functions
MINOLTA-QMS magicolor 330ÎBM Network Printer 12 PCLÎBM Network Printer 12 (PCL)ÊPSON
TM-T88II(R) ReceiptÂcrobat PDFWriterÂcrobat Distiller^\\PEGASUS\HP5P
Once the string is obtained, it becomes a matter of parsing it to extract each token that composes it. Such thing is
easy to achieve with FOCUS.FLL thanks to some token functions such as STR_numtok() and STR_ntoken() . What
follows is an example of such an extraction:
LOCAL szPrinters
LOCAL OldSep
LOCAL i
&& Get all the printers that are installed locally on the system
m.szPrinters = PRN_EnumPrinters()
&& If we could obtain something worth it

IF ( ! EMPTY( m.szPrinters ) )
&& Display the list of printers (each printer is separated
&& from the other with a caret (^)
? m.szPrinters && MINOLTA-QMS magicolor 330ÎBM Network Printer 12 PCL^
&& IBM Network Printer 12 (PCL)ÊPSON TM-T88II(R) Receipt^
&& Acrobat PDFWriterÂcrobat Distiller^\\PEGASUS\HP5P
&& Now, we will extract each printer name
&& First, let's position a new separator (the caret)
m.OldSep = STR_setsep( "^" )
&& For each printer found
FOR i = 1 TO STR_numtok( m.szPrinters )
&& Extract the name and display it
? STR_ntoken( i,m.szPrinters )
NEXT
&& Reset the separator
ELSE
? "Error:",PRN_LastError()
ENDIF
Obtaining a Printer Properties
Now that all the installed printers can be listed, either by calling the PRN_EnumPrinters() or the APRINTERS()
function, we would like to be able to determine the properties of a specific printer.

Printer Functions
PRN_color() : Color printer to render color or monochrome

output
Syntax
PRN_color( [nNew] )  nColor
Parameters
nNew new color setting (same values as nColor )
Returns
nColor color setting.
Color 1
Monochrome 2
PRN_copies() : Number of copies printed if the device

supports multiple-page copies
Syntax
PRN_copies( [nNew] )  nCopies
Parameters
nNew Optional parameter. When passed it updates the internal DeviceCapabilities structure of
FOCUS. Number of copies to position printer driver with.
Returns
nCopies number of copies.
PRN_device() : Device name

Syntax
PRN_device()  cDevice
Parameters
None.
Returns
cDevice Device unique string.
Example
IF ( ! PRN_capa() )
? "FOCUS was unable to read current printer driver"
ELSE
? "Current printer :" + PRN_device()
ENDIF

Printer Functions
PRN_dialog() : Displays a dialog box to setup application
printer
Syntax
PRN_dialog( nFrom,nTo,nMin,nMax,nCopies )  lSuccess
Parameters
nFrom starting page number.
nTo ending page number.
nMin minimum page number.
nMax maximum page number.
nCopies starting page number.
Returns
lSuccess .T. if FOCUS was able to access current printer driver and the user did press the OK button;
.F. otherwise.
PRN_driver() : Printer driver version number

Syntax
PRN_driver()  nVersion
Parameters
None.
Returns
nVersion Specifies the printer driver version number assigned by the developer.
Example
IF ( ! PRN_capa() )
ELSE
? "Driver v. :" + LTRIM( STR( PRN_driver() ) )
ENDIF
PRN_drv() : Printer driver name.

Comment
When calling PRN_capa() two different structures are updated : a DEVMODE and a DEVNAMES structure. The
dmDeviceName of the DEVMODE structure retains the same value as the Device member of the DEVNAMES structure.
PRN_device() queries the information which is stored in the DEVMODE structure whereas the PRN_name() function
queries the same information in the DEVNAMES structure.
Having both structures constantly updated also has a major advantage : the DEVNAMES structure also retains the
name of the driver associated with the current default printer and the port it is connected to.
The PRN_drv() function queries the driver name from the DEVNAMS structure.

Printer Functions
Syntax
PRN_drv()  szDriver
Parameters
None.
Returns
szDriver Printer driver name.
Example
IF ( ! PRN_capa() )
ELSE
? "Current printer driver :" + PRN_drv()
ENDIF
PRN_duplex() : Double-sided printing.

Syntax
PRN_duplex( [nNew] )  nDuplex
Parameters
FOCUS. Same values as nDuplex .
Returns
nDuplex duplex mode.
1 Simplex
2 Horizontal
3 Vertical
PRN_EnumPrinters() : Enumerates available printers.

Syntax
PRN_EnumPrinters()  szPrinters
Parameters
None.
Returns
szPrinters serialized string of printers or an empty string if an error occurred. The string is a caret ( ^)
separated list.
Example
LOCAL szPrinters
LOCAL OldSep
LOCAL i
&& Get all the printers that are installed locally on the system
m.szPrinters = PRN_EnumPrinters()
&& If we could obtain something worth it

Printer Functions
IF ( ! EMPTY( m.szPrinters ) )
&& Display the list of printers (each printer is separated
&& from the other with a caret (^)
? m.szPrinters && MINOLTA-QMS magicolor 330ÎBM Network Printer 12 PCL^
&& IBM Network Printer 12 (PCL)ÊPSON TM-T88II(R) Receipt^
&& Acrobat PDFWriterÂcrobat Distiller^\\PEGASUS\HP5P
&& Now, we will extract each printer name
&& First, let's position a new separator (the caret)
&& For each printer found
FOR i = 1 TO STR_numtok( m.szPrinters )
&& Extract the name and display it
? STR_ntoken( i,m.szPrinters )
NEXT
&& Reset the separator
ELSE
? "Error:",PRN_LastError()
ENDIF
PRN_extra() : Size of the optional dmDriverData member for

device-specific data
Special
Don’t use this function so far. It should be an internal of FOCUS.
Syntax
PRN_extra()  nSize
Parameters
None.
Returns
nSize size of the dmDriverData member.
PRN_fields() : Set of flags that indicate which members of the

DEVMODE structure have been initialized.
Syntax
PRN_fields()  nFlags
Parameters
None.
Returns
nFlags flags that have been updated.
0x0000001L DM_ORIENTATION
0x0000002L DM_PAPERSIZE
0x0000004L DM_PAPERLENGTH
0x0000008L DM_PAPERWIDTH
0x0000010L DM_SCALE
0x0000100L DM_COPIES
0x0000200L DM_DEFAULTSOURCE
0x0000400L DM_PRINTQUALITY

Printer Functions
0x0000800L DM_COLOR
0x0001000L DM_DUPLEX
0x0002000L DM_YRESOLUTION
0x0004000L DM_TTOPTION
Example
IF ( ! PRN_capa() )
ELSE
IF ( PRN_fields() = 0 )
? "No field has been updated by the driver"
ENDIF
ENDIF
PRN_GetDefaultPrinter() : Gets the default printer.

Syntax
PRN_GetDefaultPrinter()  szPrinterDef
Parameters
None.
Returns
szPrinterDef name of the default printer, its driver and port.
Example
LOCAL szDefault
m.szDefault = PRN_GetDefaultprinter()
IF ( ! PRN_SetDefaultPrinter( "HP LaserJet 5P,HPPCL5MS,\\Pegasus\hp5p" ) )

? "Cannot set the default printer"
ENDIF
&& When we're done ... let's restore the default printer
PRN_SetdefaultPrinter( m.szDefault )
PRN_GetDrvInfo() : Retrieves driver data for the specified

printer.
Syntax
PRN_GetDrvInfo( szPrinter )  szDriverSettings
Parameters
szPrinter Name of the printer or print server.
Returns
szDriverSettings tokenized string. The string is prefixed with "WINNT:" if it applies to Windows NT, or
"WIN95:" if it applies to Windows 95, which makes it easy in your own code to distinguish
between these two environments.
Windows NT :
Token  Member Description

1 pName Specifies the name of the driver (for example, "HP

Printer Functions
LaserJet 5P")
2 pEnvironment Specifies the environment for which the driver was
written (for example, "Windows x86" or "Windows NT
R4000" or "Windows 4.0")
3 pDriverPath Specifies a filename or full path and filename for the
file that contains the device driver (for example,
"C:\WINDOWS\SYSTEM\HPPCL5MS.DRV")
4 pDataFile Specifies a filename or a full path and filename for the
file that contains driver data (for example,
5 pConfigFile Specifies a filename or a full path and filename for the
device driver's configuration dynamic-link library (for
example, "C:\WINDOWS\SYSTEM\HPPCL5MS.DRV")
Windows 95 :
Token  Member Description

1 pName Specifies the name of the driver (for example, "HP
LaserJet 5P")
2 pEnvironment Specifies the environment for which the driver was
written (for example, "Windows x86" or "Windows NT
R4000" or "Windows 4.0")
3 pDriverPath Specifies a filename or full path and filename for the
file that contains the device driver (for example,
4 pDataFile Specifies a filename or a full path and filename for the
file that contains driver data (for example,
5 pConfigFile Specifies a filename or a full path and filename for the
device driver's configuration dynamic-link library (for
example, "C:\WINDOWS\SYSTEM\HPPCL5MS.DRV")
6 pHelpFile Specifies a filename or a full path and filename for the
device driver's help file (for example, "UNIDRV.HLP")
7 pDependentFiles Specifies the files the driver is dependent on. Each
filename in the string is also terminated with a null (for
example,
"HPPCL5MS.DRV;PJLMON.DLL;UNIDRV.DLL;UNIDRV.HLP
;ICONLIB.DLL;FINSTALL.DLL;FINSTALL.HLP"). Each
file is separated from the other by a ";" character.
8 pMonitorName Specifies a language monitor (for example, "PJL
monitor"). This member can be NULL and should be
specified only for printers capable of bi-directional
communication
9 pDefaultDataType Specifies the default data type of the print job (for
example, "EMF" or "RAW")
Example
LOCAL i,j, OldSep, nTokens, szDrvInfo
APRINTERS( gaPrns )
OldSep = STR_setsep( "," )
CLEAR
FOR i = 1 TO ALEN( gaPrns ) STEP 2

szDrvInfo = PRN_GetDrvInfo( gaPrns[i] )
IF ( LEFT( szDrvInfo,5 ) == "WIN95" )

? "Under Windows 95"
ELSE
? "Under Windows NT"
ENDIF
szDrvInfo = SUBSTR( szDrvInfo,7 )
? "Driver name : " , STR_ntoken( 1,szDrvInfo )

? "Driver written for : " , STR_ntoken( 2,szDrvInfo )
? "Driver path : " , STR_ntoken( 3,szDrvInfo )
? "Driver's data file : " , STR_ntoken( 4,szDrvInfo )

Printer Functions
? "Driver's configuration file : " , STR_ntoken( 5,szDrvInfo )
IF ( ! SYS_isNT() )
? "Driver's help file: " , STR_ntoken( 6,szDrvInfo )
? "Files the driver depends on : ", STR_ntoken( 7,szDrvInfo )
? "Language monitor : " , STR_ntoken( 8,szDrvInfo )
? "Default data type : " , STR_ntoken( 9,szDrvInfo )
ENDIF
WAIT WINDOW STR_ntoken( 1,szDrvInfo ) TIMEOUT 10

CLEAR
NEXT
Here is a screen capture of an instance of the ErrorForm class which uses the PRN_GetDrvInfo() to construct a
list of all printers installed on the system :
PRN_GetJobs() : List all printing jobs for a given printer.

Syntax
PRN_GetJobs( szPrinter )  szJobs
Parameters
szPrinter printer for which the jobs need to be obtained.
Returns
szJobs a serialized string with each job set as a separate token. All jobs are separated from each other
by a caret (^).
PRN_GetPrnData() : Retrieves information about a specified

printer
Special
This is one of two functions that should work OK under Windows 95. It still should be fine tuned to work under
Windows NT.
Because this function actually replaces a lot of functions that worked under FoxPro 2.6, and because we didn't want to
duplicate too much information, we will refer to the old routine. For example, PRN_GetPrnData("HP LaserJet
Printer Functions
5P",12) is actually identical to set the default printer to "HP LaserJet 5P" , and get the PRN_copies() value
(12 is to be used to acquire the number of copies).
Special
Most the printer information is stored in the registry ( HKEY_LOCAL_MACHINE\System\CurrentControlSet\
Control\Print\Printers ). For example, here is a screen capture of the settings pertaining to a "HP LaserJet 5P"
printer installed on our system :
Syntax
PRN_GetPrnData( szPrinter,nInfo )  xValue
Parameters
szPrinter name of the printer or print server.
nInfo information required. This can be one of the values listed in the following table:
Description Value See Function

FW_PRN_DMDEVICENAME 1 PRN_device()
FW_PRN_DMSPECVERSION 2 PRN_spec()
FW_PRN_DMDRIVERVERSION 3 PRN_driver()
FW_PRN_DMSIZE 4 PRN_size()
FW_PRN_DMDRIVEREXTRA 5 PRN_extra()
FW_PRN_DMFIELDS 6 PRN_fields()
FW_PRN_DMORIENTATION 7 PRN_orient()
FW_PRN_DMPAPERSIZE 8 PRN_paperS()
FW_PRN_DMPAPERLENGTH 9 PRN_paperL()
FW_PRN_DMPAPERWIDTH 10 PRN_paperW()
FW_PRN_DMSCALE 11 PRN_scale()
FW_PRN_DMCOPIES 12 PRN_copies()
FW_PRN_DMDEFAULTSOURCE 13 PRN_source()
FW_PRN_DMPRINTQUALITY 14 PRN_qualit()
FW_PRN_DMCOLOR 15 PRN_color()
FW_PRN_DMDUPLEX 16 PRN_duplex()
FW_PRN_DMYRESOLUTION 17 PRN_resolu()
FW_PRN_DMTTOPTION 18 PRN_TTopt()
FW_PRN_DMCOLLATE 19 N/A
FW_PRN_DMFORMNAME 20 N/A
FW_PRN_DMLOGPIXELS 21 N/A
FW_PRN_DMBITSPERPEL 22 N/A
FW_PRN_DMPELSWIDTH 23 N/A
FW_PRN_DMPELSHEIGHT 24 N/A
FW_PRN_DMDISPLAYFLAGS 25 N/A
FW_PRN_DMDISPLAYFREQUENCY 26 N/A
FW_PRN_DMICMMETHOD 27 N/A

Printer Functions
FW_PRN_DMICMINTENT 28 N/A
FW_PRN_DMMEDIATYPE 29 N/A
FW_PRN_DMDITHERTYPE 30 N/A
FW_PRN_DMICCMANUFACTURER 31 N/A
FW_PRN_DMICCMODEL 32 N/A
FW_PRN_PSERVERNAME 1000
FW_PRN_PPRINTERNAME 1001
FW_PRN_PSHARENAME 1002
FW_PRN_PPPORTNAME 1003
FW_PRN_PDRIVERNAME 1004
FW_PRN_PCOMMENT 1005
FW_PRN_PLOCATION 1006
FW_PRN_PSETFILE 1007
FW_PRN_PPRINTPROCESSOR 1008
FW_PRN_PDATATYPE 1009
FW_PRN_GIVEUSEFULNUM 5000 N/A
FW_PRN_GIVEUSEFULSTR 5001 N/A
FW_PRN_ATTRIBUTES 5002 N/A
FW_PRN_PRIORITY 5003 N/A
FW_PRN_DEFAULTPRIORITY 5004 N/A
FW_PRN_STARTTIME 5005 N/A
FW_PRN_UNTILTIME 5006 N/A
FW_PRN_STATUS 5007 N/A
FW_PRN_JOBCOUNT 5008 N/A
FW_PRN_AVERAGEPPM 5009 N/A
FW_PRN_GIVETHEMALL 9000 Not supported
The developer should pay extra attention to the FW_PRN_GIVEUSEFULNUM and

FW_PRN_GIVEUSEFULSTR types. Both types result in getting a string. The string comma delimited.
Each token represents a useful information :
FW_PRN_GIVEUSEFULNUM
Token  Description
1 dmOrientation
2 dmPaperSize
3 dmPaperLength
4 dmPaperWidth
5 dmScale
6 dmCopies
7 dmDefaultSource
8 dmPrintQuality
9 dmColor
10 dmDuplex
11 dmYResolution
12 dmTTOption
13 dmCollate
FW_PRN_GIVEUSEFULSTR
Token  Description
1 dmDeviceName
2 pServerName
3 pPrinterName
4 pShareName
5 pPortName
6 pDriverName
7 pComment
8 pLocation
9 pSepFile
10 pPrintprocessor
11 pDataType
12 pParameters
Returns
xValue value returned by the function according to the type of information that was requested.

Printer Functions
Example
#define PRINTER_STATUS_PAUSED 0x00000001
#define PRINTER_STATUS_ERROR 0x00000002
#define PRINTER_STATUS_PENDING_DELETION 0x00000004
#define PRINTER_STATUS_PAPER_JAM 0x00000008
#define PRINTER_STATUS_PAPER_OUT 0x00000010
#define PRINTER_STATUS_MANUAL_FEED 0x00000020
#define PRINTER_STATUS_PAPER_PROBLEM 0x00000040
#define PRINTER_STATUS_OFFLINE 0x00000080
#define PRINTER_STATUS_IO_ACTIVE 0x00000100
#define PRINTER_STATUS_BUSY 0x00000200
#define PRINTER_STATUS_PRINTING 0x00000400
#define PRINTER_STATUS_OUTPUT_BIN_FULL 0x00000800
#define PRINTER_STATUS_NOT_AVAILABLE 0x00001000
#define PRINTER_STATUS_WAITING 0x00002000
#define PRINTER_STATUS_PROCESSING 0x00004000
#define PRINTER_STATUS_INITIALIZING 0x00008000
#define PRINTER_STATUS_WARMING_UP 0x00010000
#define PRINTER_STATUS_TONER_LOW 0x00020000
#define PRINTER_STATUS_NO_TONER 0x00040000
#define PRINTER_STATUS_PAGE_PUNT 0x00080000
#define PRINTER_STATUS_USER_INTERVENTION 0x00100000
#define PRINTER_STATUS_OUT_OF_MEMORY 0x00200000
#define PRINTER_STATUS_DOOR_OPEN 0x00400000
#define PRINTER_STATUS_SERVER_UNKNOWN 0x00800000
#define PRINTER_STATUS_POWER_SAVE 0x01000000
nCopies = PRN_GetPrnData( "HP LaserJet 5P",12 ) && 12 = Number of copies

nOrientation = PRN_GetPrnData( "HP LaserJet 5P",7 ) && 7 = Orientation
? "HP LaserJet 5P"

? "Copies:" + ALLTRIM( STR( nCopies ) )
? "Orientation:" + IIF( nOrientation == 1, ;
"Portrait" , ;
"Landscape" )
&& Port assignment

? PRN_GetPrnData( "HP LaserJet 5P",1003 )
&& List all useful numeric values

? PRN_GetPrnData( "HP LaserJet 5P",5000 ) && Can produce a string similar to :
* "HP LaserJet 5P,(null),HP LaserJet 5P,(null),LPT1:,HP LaserJet 5P,Imprimante 600
dpi,,,WinPrint,EMF,"
&& List all useful string values

? PRN_GetPrnData( "HP LaserJet 5P",5001 ) && Can produce a string similar to :
* "1,9,1270,762,0,1,1,600,1,1,600,4,0"
&& Obtain the status of the printer (Ready, Offline, Busy ?)

? PRN_GetPrnData( "MINOLTA-QMS magicolor 330",5007 )
FastWrite has created useful VFP classes dedicated to printer settings. Here are two screen captures from VFP
programs that use these classes to gain total control over printer settings :

Printer Functions
When clicking the Settings command button, the following form is displayed :
You can even see the comment attached to a given printer :

Printer Functions
... or see advanced settings :
... and Font settings :

Printer Functions
PRN_LastVersion() : Returns the file stamp of PRN functions.

Remark
Syntax
PRN_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\PRN.C-Mon Oct 19 15:55:22 1998" .
PRN_name() : Device name/printer name

Comment
Syntax
PRN_name()  szDevice
Parameters
None.

Printer Functions
Returns
szDevice Printer name.
Example
IF ( ! PRN_capa() )
ELSE
? "Current printer :" + PRN_name()
ENDIF
PRN_orient() : Paper orientation

Syntax
PRN_orient( [nNew] )  nOrientation
Parameters
FOCUS. 1 for Portrait mode, 2 for Landscape.
Returns
nOrientation 1 for Portrait mode, 2 for Landscape.
Example
IF ( ! PRN_capa() )
? "FOCUS was unable to read the current printer driver"
ELSE
? "Paper orientation : " + IIF( PRN_orient() == 1, ;
"Portrait" , ;
"Landscape" )
ENDIF
PRN_paperL() : Paper length, in tenths of a millimeter

Comment
If this function returns a value, it should override the paper length returned by PRN_paperS() . Such situations arise
for custom paper sizes or for such devices as dot-matrix printers that can print on a variety of page sizes.
Syntax
PRN_paperL()  nSize
Parameters
None.
Returns
nSize Paper length.
PRN_paperS() : Paper size

Syntax
PRN_paperS( [nNew] )  nSize

Printer Functions
Parameters
FOCUS. Same values as nSize .
Returns
nSize Paper size
DMPAPER_LETTER 1 Letter 8 1/2 x 11 in

DMPAPER_LETTERSMALL 2 Letter Small 8 1/2 x 11 in
DMPAPER_TABLOID 3 Tabloid 11 x 17 in
DMPAPER_LEDGER 4 Ledger 17 x 11 in
DMPAPER_LEGAL 5 Legal 8 1/2 x 14 in
DMPAPER_STATEMENT 6 Statement 5 1/2 x 8 1/2 in
DMPAPER_EXECUTIVE 7 Executive 7 1/4 x 10 1/2 in
DMPAPER_A3 8 A3 297 x 420 mm
DMPAPER_A4SMALL 10 A4 Small 210 x 297 mm
DMPAPER_B4 12 B4 250 x 354
DMPAPER_B5 13 B5 182 x 257 mm
DMPAPER_FOLIO 14 Folio 8 1/2 x 13 in
DMPAPER_QUARTO 15 Quarto 215 x 275 mm
DMPAPER_10X14 16 10x14 in
DMPAPER_NOTE 18 Note 8 1/2 x 11 in
DMPAPER_ENV_9 19 Envelope #9 3 7/8 x 8 7/8
DMPAPER_ENV_10 20 Envelope #10 4 1/8 x 9 ½
DMPAPER_ENV_12 22 Envelope #12 4 \276 x 11
DMPAPER_ENV_14 23 Envelope #14 5 x 11 ½
DMPAPER_CSHEET 24 C size sheet
DMPAPER_DSHEET 25 D size sheet
DMPAPER_ESHEET 26 E size sheet
DMPAPER_ENV_DL 27 Envelope DL 110 x 220mm
DMPAPER_ENV_C5 28 Envelope C5 162 x 229 mm
DMPAPER_ENV_B4 33 Envelope B4 250 x 353 mm
DMPAPER_ENV_ITALY 36 Envelope 110 x 230 mm
DMPAPER_ENV_MONARCH 37 Envelope Monarch 3.875 x 7.5 in
DMPAPER_ENV_PERSONAL 38 6 3/4 Envelope 3 5/8 x 6 1/2 in
DMPAPER_FANFOLD_US 39 US Std Fanfold 14 7/8 x 11 in
DMPAPER_FANFOLD_STD_GERMAN 40 German Std Fanfold 8 1/2 x 12 in
DMPAPER_FANFOLD_LGL_GERMAN 41 German Legal Fanfold 8 1/2 x 13 in
PRN_paperW() : Paper width, in tenths of a millimeter

Comment
If this function returns a value, it should override the paper width returned by PRN_paperS() . Such situations arise
for custom paper sizes or for such devices as dot-matrix printers that can print on a variety of page sizes.
Syntax
PRN_paperW()  nSize

Printer Functions
Parameters
None.
Returns
nSize Paper width.
PRN_port() : Port connection

Version
FoxPro 2.6 only.
Comment
The PRN_port() function queries the port the printer is connected to.
Syntax
PRN_port()  szPort
Parameters
None.
Returns
szPort Printer port.
PRN_qualit() : Printer resolution

Syntax
PRN_qualit()  nQuality
Parameters
None.
Returns
nQuality Default bin. There are four predefined device-independent values which are :
High resolution -4
Medium resolution -3
Low resolution -2
Draft mode -1
If a positive value is given, it specifies the number of dots per inch (dpi) and is therefore
device-dependent.

Printer Functions
PRN_resolu() : Printer resolution (y-resolution)
Syntax
PRN_resolu()  nResolution
Parameters
None.
Returns
nResolution y-resolution in dots per inch. If the printer initializes this member, the PRN_qualit() function
specifies the x-resolution in dots per inch.
PRN_scale() : Factor by which the printed output is to be

scaled
Syntax
PRN_scale()  nFactor
Parameters
None.
Returns
nFactor factor by which the printed output is to be scaled.
PRN_SetDefaultPrinter() : Sets the default printer.

Syntax
PRN_SetDefaultPrinter( szPrinterDef )  lSuccess
Parameters
szPrinterDef name of the printer to set, its driver and port.
Returns
lSuccess .T. if the printer has been successfully set; .F. if not. What the function does is very
straightforward: it simply writes the new default printer to the WIN.INI file via the
nReturn = WriteProfileString( "WINDOWS","device",_parc(1) ) call. On NT
systems this is mapped to the registry. Then we make sure that the WIN.INI file is flushed
(something that many programmers forget, but you shouldn't lose from sight that the WIN.INI
file is kept in memory whenever Windows can. In other terms, all running applications can still
think that some entries are different from what is actually written in the file). Then we issue a
warning to all running applications informing them that the WIN.INI file has changed. On a
Windows 98 system, here's the line in my [Windows] section:
[windows]
NullPort=None
SkipMouseRedetect=0
device=HP LaserJet 5P,HPPCL5MS,\\Pegasus\hp5p
C Code
FOCUSFNC FW_PRN_SetDefaultPrinter( XBASE_PARAMETERS )
/*--------------------------------------------------*/
{
Printer Functions
int nReturn;
_initparc(1);
// Write the printer name, the driver name, and the port to WIN.INI
nReturn = WriteProfileString( "WINDOWS","device",_parc(1) );
// Flush WIN.INI changes

WriteProfileString( NULL,NULL,NULL );
// Broadcast WIN.INI change to all applications
SendMessage( HWND_BROADCAST,WM_SETTINGCHANGE,0,(LPARAM) "WINDOWS" );
_deinitparc(1);
_retl( nReturn );
FOCUSFNCRETURN();
}
Example
LOCAL szDefault
m.szDefault = PRN_GetDefaultprinter()
IF ( ! PRN_SetDefaultPrinter( "HP LaserJet 5P,HPPCL5MS,\\Pegasus\hp5p" ) )

? "Cannot set the default printer"
ENDIF
&& When we're done ... let's restore the default printer
PRN_SetdefaultPrinter( m.szDefault )
PRN_SetPrnData() : Sets information in a given printer

Syntax
PRN_SetPrnData( szPrinter,nInfo,nValue|szValue )  lSuccess
Parameters
szPrinter name of the printer or print server.
nInfo information that will be updated. This can be one of the values listed in the following table:
Description Value See Function

FW_PRN_DMORIENTATION 7 For printer devices only, selects the orientation of the paper.
This member can be either DMORIENT_PORTRAIT (1) or
DMORIENT_LANDSCAPE (2).
FW_PRN_DMPAPERSIZE 8 DMPAPER_LETTER 1 Letter 8 1/2 x 11 in
DMPAPER_LETTERSMALL 2 Letter Small 8 1/2 x 11
in
DMPAPER_TABLOID 3 Tabloid 11 x 17 in
DMPAPER_LEDGER 4 Ledger 17 x 11 in
DMPAPER_LEGAL 5 Legal 8 1/2 x 14 in
DMPAPER_STATEMENT 6 Statement 5 1/2 x 8 1/2
in
DMPAPER_EXECUTIVE 7 Executive 7 1/4 x 10 1/2
in
DMPAPER_A4SMALL 10 A4 Small 210 x 297 mm
DMPAPER_B4 12 B4 250 x 354
DMPAPER_B5 13 B5 182 x 257 mm
DMPAPER_FOLIO 14 Folio 8 1/2 x 13 in
DMPAPER_QUARTO 15 Quarto 215 x 275 mm
DMPAPER_NOTE 18 Note 8 1/2 x 11 in
DMPAPER_ENV_10 20 Envelope #10 4 1/8 x 9 ½
DMPAPER_ENV_11 21 Envelope #11 4 1/2 x 10
3/8
DMPAPER_ENV_12 22 Envelope #12 4 \276 x 11
DMPAPER_ENV_14 23 Envelope #14 5 x 11 ½
DMPAPER_CSHEET 24 C size sheet
DMPAPER_DSHEET 25 D size sheet

Printer Functions
DMPAPER_ESHEET 26 E size sheet
DMPAPER_ENV_DL 27 Envelope DL 110 x 220mm
DMPAPER_ENV_ITALY 36 Envelope 110 x 230 mm
DMPAPER_ENV_MONARCH 37 Envelope Monarch 3.875 x
7.5 in
DMPAPER_ENV_PERSONAL 38 6 3/4 Envelope 3 5/8 x 6
1/2 in
DMPAPER_FANFOLD_US 39 US Std Fanfold 14 7/8 x
11 in
DMPAPER_FANFOLD_STD_GERMAN 40 German Std Fanfold 8 1/2
x 12 in
DMPAPER_FANFOLD_LGL_GERMAN 41 German Legal Fanfold 8
1/2 x 13 in
FW_PRN_DMPAPERLENGTH 9 For printer devices only, overrides the length of the paper
specified by the dmPaperSize member, either for custom
paper sizes or for devices such as dot-matrix printers that
can print on a page of arbitrary length. These values, along
with all other values in this structure that specify a physical
length, are in tenths of a millimeter.
FW_PRN_DMPAPERWIDTH 10 For printer devices only, overrides the width of the paper
specified by the dmPaperSize member.
FW_PRN_DMSCALE 11 Specifies the factor by which the printed output is to be
scaled. The apparent page size is scaled from the physical
page size by a factor of dmScale/100. For example, a
letter-sized page with a dmScale value of 50 would contain
as much data as a page of 17- by 22-inches because the
output text and graphics would be half their original height
and width.
FW_PRN_DMCOPIES 12 Selects the number of copies printed if the device supports
multiple-page copies.
FW_PRN_DMDEFAULTSOURCE 13 Specifies the paper source. To retrieve a list of the available
paper sources for a printer, use the DeviceCapabilities()
function with the DC_BINS flag.
This member can be one of the following values, or it can be
a device-specific value greater than or equal to one of the
following values:
Tray Value Tray Value
First 1 Auto 7
Only one 1 Cassette 14
Upper 1 Envelope 5
Lower 2 Envelope 6
manual
Middle 3 First 1
Manual 4 Large capacity 11
Envelope 5 Large format 10
Envelope 6 Last 14
manual
Auto 7 Lower 2
Tractor 8 Manual 4
Small format 9 Middle 3
Large format 10 Only one 1
Large capacity 11 Small format 9
Cassette 14 Tractor 8
Last 14 Upper 1
FW_PRN_DMPRINTQUALITY 14 Specifies the printer resolution. There are four predefined
device-independent values:
DMRES_HIGH
DMRES_MEDIUM
DMRES_LOW
DMRES_DRAFT
If a positive value is specified, it specifies the number of
dots per inch (DPI) and is therefore device dependent.
FW_PRN_DMCOLOR 15 Switches between color and monochrome on color printers.
Following are the possible values:
DMCOLOR_COLOR

Printer Functions
DMCOLOR_MONOCHROME
FW_PRN_DMDUPLEX 16 DMDUP_SIMPLEX Normal (nonduplex) printing.
DMDUP_HORIZONTAL Short-edge binding, that is, the long edge
of the page is horizontal.
DMDUP_VERTICAL Long-edge binding, that is, the long edge
of the page is vertical.
FW_PRN_DMYRESOLUTION 17 Specifies the y-resolution, in dots per inch, of the printer. If

the printer initializes this member, the dmPrintQuality
member specifies the x-resolution, in dots per inch, of the
printer
FW_PRN_DMTTOPTION 18 Specifies how TrueType® fonts should be printed. This
member can be one of the following values.
FW_PRN_DMCOLLATE 19 Specifies whether collation should be used when printing
multiple copies. (This member is ignored unless the printer
driver indicates support for collation by setting the
dmFields member to DM_COLLATE.) This member can be
one of the following values.
FW_PRN_DMLOGPIXELS 21 Specifies the number of pixels per logical inch. Printer
drivers do not use this member.
FW_PRN_DMBITSPERPEL 22 Specifies the color resolution, in bits per pixel, of the display
device (for example: 4 bits for 16 colors, 8 bits for 256
colors, or 16 bits for 65,536 colors). Display drivers use this
member, for example, in the
ChangeDisplaySettings() WIN32 function. Printer
FW_PRN_DMPELSWIDTH 23 Specifies the width, in pixels, of the visible device surface.
Display drivers use this member, for example, in the
drivers do not use this member
FW_PRN_DMPELSHEIGHT 14 Specifies the height, in pixels, of the visible device surface.
Display drivers use this member, for example, in the
FW_PRN_DMDISPLAYFLAGS 25 Specifies the device's display mode. This member can be a
combination of different values.
FW_PRN_DMICMMETHOD 27 Windows 95/98/Me; Windows 2000/XP: Specifies how
ICM (Image Color Management ) is handled. For a non-ICM
application, this member determines if ICM is enabled or
disabled. For ICM applications, the system examines this
member to determine how to handle ICM support. This
member can be one of the following predefined values, or a
driver-defined value greater than or equal to the value of
DMICMMETHOD_USER.
FW_PRN_DMICMINTENT 28 Windows 95/98/Me, Windows 2000/XP: Specifies
which color matching method, or intent, should be used by
default. This member is primarily for non-ICM applications.
ICM applications can establish intents by using the ICM
functions. This member can be one of the following
predefined values, or a driver defined value greater than or
equal to the value of DMICM_USER.
FW_PRN_DMMEDIATYPE 29 Windows 95/98/Me, Windows 2000/XP: Specifies the
type of media being printed on. The member can be one of
the following predefined values, or a driver-defined value
greater than or equal to the value of DMMEDIA_USER.
FW_PRN_DMDITHERTYPE 30 Windows 95/98/Me, Windows 2000/XP: Specifies how
dithering is to be done. The member can be one of the
following predefined values, or a driver-defined value
greater than or equal to the value of DMDITHER_USER.
FW_PRN_PCOMMENT 1005 Printer comment
nValue|szValue If nInfo is equal to FW_PRN_PCOMMENT, then the parameter that must be passed in a character
string (szValue). In all other cases, the parameter is an integer (nValue).
Returns

Printer Functions
Example
#define FW_PRN_DMDEVICENAME 1
#define FW_PRN_DMSPECVERSION 2
#define FW_PRN_DMDRIVERVERSION 3
#define FW_PRN_DMSIZE 4
#define FW_PRN_DMDRIVEREXTRA 5
#define FW_PRN_DMFIELDS 6
#define FW_PRN_DMORIENTATION 7
#define FW_PRN_DMPAPERSIZE 8
#define FW_PRN_DMPAPERLENGTH 9
#define FW_PRN_DMPAPERWIDTH 10
#define FW_PRN_DMSCALE 11
#define FW_PRN_DMCOPIES 12
#define FW_PRN_DMDEFAULTSOURCE 13
#define FW_PRN_DMPRINTQUALITY 14
#define FW_PRN_DMCOLOR 15
#define FW_PRN_DMDUPLEX 16
#define FW_PRN_DMYRESOLUTION 17
#define FW_PRN_DMTTOPTION 18
#define FW_PRN_DMCOLLATE 19
#define FW_PRN_DMFORMNAME 20
#define FW_PRN_DMLOGPIXELS 21
#define FW_PRN_DMBITSPERPEL 22
#define FW_PRN_DMPELSWIDTH 23
#define FW_PRN_DMPELSHEIGHT 24
#define FW_PRN_DMDISPLAYFLAGS 25
#define FW_PRN_DMDISPLAYFREQUENCY 26
#define FW_PRN_DMICMMETHOD 27
#define FW_PRN_DMICMINTENT 28
#define FW_PRN_DMMEDIATYPE 29
#define FW_PRN_DMDITHERTYPE 30
#define FW_PRN_DMICCMANUFACTURER 31
#define FW_PRN_DMICCMODEL 32
#define FW_PRN_PSERVERNAME 1000
#define FW_PRN_PPRINTERNAME 1001
#define FW_PRN_PSHARENAME 1002
#define FW_PRN_PPORTNAME 1003
#define FW_PRN_PDRIVERNAME 1004
#define FW_PRN_PCOMMENT 1005
#define FW_PRN_PLOCATION 1006
#define FW_PRN_PSEPFILE 1007
#define FW_PRN_PPRINTPROCESSOR 1008
#define FW_PRN_PDATATYPE 1009
#define FW_PRN_PPARAMETERS 1010
#define FW_PRN_GIVEUSEFULNUM 5000
#define FW_PRN_GIVEUSEFULSTR 5001
#define FW_PRN_ATTRIBUTES 5002
#define FW_PRN_PRIORITY 5003
#define FW_PRN_DEFAULTPRIORITY 5004
#define FW_PRN_STARTTIME 5005
#define FW_PRN_UNTILTIME 5006
#define FW_PRN_STATUS 5007
#define FW_PRN_JOBCOUNT 5008
#define FW_PRN_AVERAGEPPM 5009
#define FW_PRN_GIVETHEMALL 9000
nCopies = PRN_GetPrnData("MINOLTA-QMS magicolor 330",FW_PRN_DMCOPIES )

nOrientation = PRN_GetPrnData("MINOLTA-QMS magicolor 330",FW_PRN_DMORIENTATION )
&& In general, most printers are set by default with 1 copy, and portrait mode
? "Before any change ...","Copies",nCopies,"Orientation",nOrientation
&& Here we intend to set it with 3 copies and in Landscape mode

PRN_SetPrnData("MINOLTA-QMS magicolor 330",FW_PRN_DMCOPIES ,4 )
PRN_SetPrnData("MINOLTA-QMS magicolor 330",FW_PRN_DMORIENTATION,2 )
nCopies = PRN_GetPrnData("MINOLTA-QMS magicolor 330",FW_PRN_DMCOPIES )

nOrientation = PRN_GetPrnData("MINOLTA-QMS magicolor 330",FW_PRN_DMORIENTATION )
? "After calling PRN_SetPrnData()","Copies",nCopies,"Orientation",nOrientation

Printer Functions
PRN_size() : Size of the DEVMODE structure
Special
Don’t use this function so far. It should be an internal of FOCUS.
Syntax
PRN_size()  nSize
Parameters
None.
Returns
nSize Size of the DEVMODE structure.
PRN_source() : Default bin from which the paper is fed

Caution
This function is superseded by the PRN_SetPrnData() function.
Syntax
PRN_source( [nNew] )  nBin
Parameters
FOCUS. Same values as nBin .
Returns
nBin Default bin.
Tray Value Tray Value

First 1 Auto 7
Only one 1 Cassette 14
Upper 1 Envelope 5
Lower 2 Envelope 6
manual
Middle 3 First 1
Manual 4 Large capacity 11
Envelope 5 Large format 10
Envelope 6 Last 14
manual
Auto 7 Lower 2
Tractor 8 Manual 4
Small format 9 Middle 3
Large format 10 Only one 1
Large capacity 11 Small format 9
Cassette 14 Tractor 8
Last 14 Upper 1

Printer Functions
PRN_spec() : Version number of the DEVMODE structure
Syntax
PRN_spec()  nVersion
Parameters
None.
Returns
nVersion version number of the DEVMODE structure. For Windows 3.1 it should be 0x30A (778)
Example
IF ( ! PRN_capa() )
ELSE
? "Windows v. :" + LTRIM( STR( PRN_spec() ) )
ENDIF
PRN_TTopt() : How should TrueType fonts be printed?

Syntax
PRN_TTopt()  nResolution
Parameters
None.
Returns
nResolution y-resolution in dots per inch. If the printer initializes this member, the PRN_qualit() function
specifies the x-resolution in dots per inch.
Print TrueType as graphics. Default action for 1

dot-matrix printers.
Download TrueType fonts as soft fonts. This is 2
the default action for Hewlett-Packard
printers that use PCL
Substitute device fonts for TrueType fonts. 3
This is the default action for PostScript
printers

Registry Functions
Registry Functions

Registry Functions
REG_CreateKey() : Creates a key in the Windows registry.

Syntax
REG_CreateKey( szRoot,szKey )  nSuccess
Parameters
szRoot root key.
szKey key to create.
Returns
nSuccess 0 in case of success.
Example
IF ( REG_CreateKey( "HKEY_LOCAL_MACHINE","Software\AAA" ) )
? "The key was successfully created"
ENDIF
REG_CreateValue() : Creates a value in the Windows registry.

Syntax
REG_CreateValue( szRoot,szPath,szValue,szData|nData )  lSuccess
Parameters
szRoot root key.
szPath path to access.
szValue value to query.
szData|nData data to write for szValue . This can be only strings or integers.

Registry Functions
Returns
Example
? REG_CreateValue( "HKEY_LOCAL_MACHINE" , ;
"SOFTWARE\FastWrite\Trees\1.0", ;
"Test" , ;
"Hello World" , ;
)
? REG_CreateValue( "HKEY_LOCAL_MACHINE" , ;
"SOFTWARE\FastWrite\Trees\1.0", ;
"Test2" , ;
43 , ;
)
REG_DeleteKey() : Deletes a key in the Windows registry.

Syntax
REG_DeleteKey( szRoot,szPath,szValue )  szString
Parameters
szRoot root key.
Returns
szString character string. So far, only character strings can be returned by the REG_QueryValue()
function.
Example
????????????
REG_DeleteValue() : Deletes a value in the Windows registry.

Syntax
REG_DeleteValue( szRoot,szPath,szValue )  szString
Parameters
szRoot root key.
Returns
function.
Example
????????????

Registry Functions
REG_EnumKeyEx() : Enumerates all subkeys of a given key of
the Windows registry.
Syntax
REG_EnumKeyEx( szRoot,szPath )  szKeys
Parameters
szRoot root key.
Returns
szKeys character string that represents all the subkeys of a given key ( szPath ). All keys are separated
from each other by a caret (^).
Example
LOCAL nPrograms
LOCAL szPrograms
LOCAL szThisProgram
LOCAL OldSep
LOCAL i
&& Enumerates all keys: a long string will be returned

m.szPrograms = REG_EnumKeyEx( "HKEY_LOCAL_MACHINE","SOFTWARE\FastWrite" )
&& The string is delimited with carets (^)

m.szOldSep = STR_setsep( "^" )
&& How many tokens rae found in that string

m.nPrograms = STR_numtok( m.szPrograms )
&& Enumerate each entry

? "List of installed programs:"
FOR i = 1 TO m.nPrograms
m.szThisProgram = ALLTRIM( STR_ntoken( i,m.szPrograms ) )
? "#",i,"...",m.szThisProgram
NEXT
&& STR_setsep( m.szOldSep )
REG_LastVersion() : Returns the file stamp of REG functions.

Remark
Syntax
REG_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\REG.C-Mon Oct 19 15:55:22 1998" .

Registry Functions
REG_QueryValue() : Gets data from the Registry.
Syntax
REG_QueryValue( szRoot,szPath,szValue )  szString
Parameters
szRoot root key.
Returns
function.
Example
? REG_QueryValue( "HKEY_LOCAL_MACHINE" , ;
"SOFTWARE\Microsoft\Windows\CurrentVersion", ;
"ProductId" ) && 31895-OEM-0006663-59319

Regular Expressions Functions

Function Synopsis
The implementation of Regular Expressions in the framework of FOCUS.FLL is based on code that was first created by
the University of California.
"Copyright 1991 The Regents of the University of California.

"All rights reserved. Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the
following acknowledgement: "This product includes software developed by the
University of California, Berkeley and its contributors."
4. Neither the name of the University nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior written
permission.
How To Use Regular Expressions?

Regular expressions work in a different way than simple substring searches. You first need to compile what you're
looking for, then you can perform the search in a string.
The compilation of what you're looking for must be achieved with RG_Compile() . The real search must be achieved
via the RG_Execute() function.
The RG_Compile() function compiles a regular expression into a structure of type regexp (internal to FOCUS.FLL ),
and returns a pointer to it (kept internally). In final, the result of the function is either a logical true ( .T.) or a logical
false (.F. ) to indicate success or failure.
If the return value of RG_Compile() was .T. , then a subsequent call to RG_Execute() can be carried out.
The RG_Execute() function determines if a match can be found in the string that was passed to it. The function uses
the internal structure that was filled thanks to the previous call to RG_Compile() .
For example, here's how you would determine that "World" is found in "Hello World" :
IF ( RG_Compile( "World" )
IF( RG_Execute( "Hello World" ) )
? "We found it"
ELSE
? "We dind't find it"
ENDIF
ENDIF
… of course, in this example, a match is found.
How to Write Regular Expressions?

A regular expression is zero or more branches , separated by '|'. It matches anything that matches one of the
branches.

A branch is zero or more pieces , concatenated. It matches a match for the first, followed by a match for the second,
etc.
A piece is an atom possibly followed by '*', '+', or '?'. An atom followed by '*' matches a sequence of 0 or more
matches of the atom. An atom followed by '+' matches a sequence of 1 or more matches of the atom. An atom
followed by '?' matches a match of the atom, or the null string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below),
'.' (matching any single character), '^' (matching the null string at the beginning of the input string), '$'
(matching the null string at the end of the input string), a '\' followed by a single character (matching that
character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in '[]' . It normally matches any single character from the sequence. If
the sequence begins with '^', it matches any single character not from the rest of the sequence. If two characters in
the sequence are separated by '-', this is shorthand for the full list of ASCII characters between them (e.g. '[0-9]'
matches any decimal digit). To include a literal ']' in the sequence, make it the first character (following a possible
'^' ). To include a literal '-', make it the first or last character.
How Will Ambiguity Be Solved?

If a regular expression could match two different parts of the input string, it will match the one which begins earliest.
If both begin in the same place but match different lengths, or match the same length in different ways, life gets
messier, as follows.
In general, the possibilities in a list of branches are considered in left-to-right order, the possibilities for '*' , '+' , and
'?' are considered longest-first, nested constructs are considered from the outermost in, and concatenated constructs
are considered leftmost-first. The match that will be chosen is the one that uses the earliest possibility in the first
choice that has to be made. If there is more than one choice, the next will be made in the same manner (earliest
possibility) subject to the decision on the first choice. And so forth.
For example, '(ab|a)b*c' could match 'abc' in one of two ways. The first choice is between 'ab' and 'a'; since
'ab' is earlier, and does lead to a successful overall match, it is chosen. Since the 'b' is already spoken for, the
'b*' must match its last possibility — the empty string — since it must respect the earlier choice.
In the particular case where no '|' s are present and there is only one '*' , '+' , or '?' , the net effect is that the
longest possible match will be chosen. So 'ab*' , presented with 'xabbbby' , will match 'abbbb' . Note that if
'ab*' , is tried against 'xabyabbbz' , it will match 'ab' just after 'x', due to the begins-earliest rule. (In effect,
the decision on where to start the match is the first choice to be made, hence subsequent choices must respect it even
if this leads them to less-preferred alternatives.)
Determining the Substrings that Were Matched

The members of a regexp structure (internal of FOCUS.FLL) include at least the following information:
char *startp[10];
char *endp[10];
Once a successful RG_Execute() has been done, each startp-endp pair describes one substring within the string ,
with the startp pointing to the first character of the substring and the endp pointing to the first character following
the substring. The 0th substring is the substring of string that matched the whole regular expression. The others are
those substrings that matched parenthesized expressions within the regular expression, with parenthesized
expressions numbered in left-to-right order of their opening parentheses.
The RG_sub() function copies source to destination, making substitutions according to the most recent
RG_Execute() performed. Each instance of '&' in source is replaced by the substring indicated by startp and
endp . Each instance of '\n' , where n is a digit, is replaced by the substring indicated by startp n and endp n . To
get a literal '&' or '\n' into destination , prefix it with '\'; to get a literal '\' preceding '&' or '\n' , prefix it
with another '\' .
Useful Examples
Example #1: We look for a pattern that is composed of two parts: part #1 can either be "Hello" or "Good
morning" ; part #2 must be "World" . Here's how we build the pattern, and the result of few tests:
? RG_Compile( "(Hello|Good morning) World" ) && .T.

? RG_Execute( "Good World" ) && .F.
? RG_Execute( "Hello World" ) && .T.
? RG_Execute( "Good morning World" ) && .T.
? RG_Execute( "Good Morning World" ) && .F.

Example #2: Same example as above, but this time the first part can be found or not: we accept that part #1 is
absent BUT part #2 must be met:
? RG_Compile( "(Hello|Good morning)*World" ) && .T.

? RG_Execute( "Good World" ) && .T.
? RG_Execute( "Hello World" ) && .T.
? RG_Execute( "Good morning World" ) && .T.
? RG_Execute( "Good Morning World" ) && .T.
? RG_Execute( "World" ) && .T.
? RG_Execute( "world" ) && .F.
Example #3: We want to match a string that contains a pattern formed of 2 parts: part #1 must contain a number
made of at least two digits; part #2 must contain the word "dog" :
? RG_Compile( "[0-9][0-9] dog" ) && .T.

? RG_Execute( "Hello World" ) && .F.
? RG_Execute( "We have 7 dogs" ) && .F.
? RG_Execute( "We have 71 dogs" ) && .T.
Example #4: Same example as above, but this time, we also want to match if we have no dog at all:
? RG_Compile( "(no dog|[0-9][0-9] dog)" ) && .T.

? RG_Execute( "We have no dog" ) && .T.
The following code does exactly the same thing, but the pattern was constructed differently:
? RG_Compile( "(no|[0-9][0-9]) dog" ) && .T.

? RG_Execute( "We have 00 dog" ) && .T.
Examine the last line: a match was found for "00". Now, what can be done if we don't want the first
letter to be a 0? We can simply change the range of the first digit:
? RG_Compile( "(no|[1-9][0-9]) dog" ) && .T.

? RG_Execute( "We have 00 dog" ) && .F.
? RG_Execute( "We have 10 dog" ) && .T.
Example #4: Same example as above, but this time, we want to match only if we have between 10 and 29 dogs:
? RG_Compile( "(no|[1,2][0-9]) dog" ) && .T.


RG_Compile() : Compiles a pattern that will be used in

subsequent calls to RG_Execute().
Syntax
RG_Compile( szPattern )  lSuccess
Parameters
szPattern the pattern to compile.
Returns
lSuccess .T. if szPattern could be compiled successfully; .F. otherwise.
Example
RG_Execute() : Performs a regular expression search.

Remark
Before using RG_Execute() , you must prepare the pattern to look for with RG_Compile() .
Syntax
RG_Execute( szString )  lSuccess
Parameters
szString the string to search.
Returns
lSuccess .T. if szString contains the pattern that was compiled previously by RG_Compile() . .F.
otherwise.
Example
RG_Match() : match of the whole last regular expression.

Syntax
RG_Match()  szMatch

Parameters
None.
Returns
szMatch the match of the whole regular expression or an empty string ("") in case of failure.
Example
? RG_Compile( "(no|a lot of) dog" ) && .T.
? RG_Execute( "I have no dog" ) && .T.
? RG_Match() && "no dog"
? RG_Execute( "I have a lot of dogs" ) && .T.
? RG_Match() && "a lot of dogs"

Screen Functions
Screen Functions

Screen Functions
SCR_BitmapHeight() : Height of bitmaps contained in title bar.

Alias
SYS_BitmapHeight()
Syntax
SCR_BitmapHeight()  nPixels
Parameters
None.
Returns
nPixels number of Y pixels.
SCR_BitmapWidth() : Width of bitmaps contained in title bar.

Alias
SYS_BitmapWidth()
Syntax
SCR_BitmapWidth()  nPixels
Parameters
None.
Returns
nPixels number of X pixels.
SCR_ColorDepth() : Determines screen color depth

Syntax
SCR_ColorDepth()  nColors
Parameters
None.
Returns
nColors number of colors in the current screen resolution.
Example
IF ( SCR_ColorDepth() < 32768 )
? "Warning : This application uses highcolor bitmaps"
ENDIF

Screen Functions
SCR_cols() : Displays width in pixels
Syntax
SCR_cols()  nColumns
Parameters
None.
Returns
nColumns number of X pixels.
Example
? "Display resolution", ;
SCR_rows(), ;
SCR_col()
SCR_EnumDisplaySettings() : Retrieves information about one

of the graphics modes for a display device.
Syntax
SCR_EnumDisplaySettings(i)  lSuccess
Parameters
i Graphics mode. Graphics mode indexes start at zero. To obtain information for all of a display
device's graphics modes, make a series of calls to SCR_EnumDisplaySettings(), as follows: Set
i to zero for the first call, and increment i by one for each subsequent call. Continue calling the
function until the return value is .F..
Returns
Example
LOCAL I
LOCAL x
LOCAL nFreq
m.i = 0 && Index start position

m.x = SCR_EnumDisplaySettings( i ) && Enumerate all settings
DO WHILE ( m.x ) && While success
m.nFreq = SCR_GetDMMember(26) && Obtain frequency member of the dm struct.
IF ( m.nFreq > 1 ) && If frequency is above 1 Hz

? ALLTRIM( STR( m.nFreq ) ) + " Hz" && Display the supported frequency
ENDIF
m.i = m.i + 1 && Next Display Setting

m.x = SCR_EnumDisplaySettings(m.i) && Get values of the next setting
ENDDO

Screen Functions
SCR_GetDMMember() : Retrieves a member of the internal
DEVMODE structure that is populated after a call to
SCR_EnumDisplaySettings().
Syntax
SCR_GetDMMember(i)  xRetVal
Parameters
i Member to query information about.
Returns
xRetVal Value of the member that must be queried. The return type depends on the member to query.
For example, if i is equal to 1, a character string is returned. If i is equal to 26, a numeric
value is returned.
FW_PRN_DMDEVICENAME 1
FW_PRN_DMSPECVERSION 2
FW_PRN_DMDRIVERVERSION 3
FW_PRN_DMSIZE 4
FW_PRN_DMDRIVEREXTRA 5
FW_PRN_DMFIELDS 6
FW_PRN_DMORIENTATION 7
FW_PRN_DMPAPERSIZE 8
FW_PRN_DMPAPERLENGTH 9
FW_PRN_DMPAPERWIDTH 10
FW_PRN_DMSCALE 11
FW_PRN_DMCOPIES 12
FW_PRN_DMDEFAULTSOURCE 13
FW_PRN_DMPRINTQUALITY 14
FW_PRN_DMCOLOR 15
FW_PRN_DMDUPLEX 16
FW_PRN_DMYRESOLUTION 17
FW_PRN_DMTTOPTION 18
FW_PRN_DMCOLLATE 19
FW_PRN_DMFORMNAME 20
FW_PRN_DMLOGPIXELS 21
FW_PRN_DMBITSPERPEL 22
FW_PRN_DMPELSWIDTH 23
FW_PRN_DMPELSHEIGHT 24
FW_PRN_DMDISPLAYFLAGS 25
FW_PRN_DMDISPLAYFREQUENC 26
Y
FW_PRN_DMICMMETHOD 27
FW_PRN_DMICMINTENT 28
FW_PRN_DMMEDIATYPE 29
FW_PRN_DMDITHERTYPE 30
FW_PRN_DMICCMANUFACTURER 31
FW_PRN_DMICCMODEL 32
Example
LOCAL I
LOCAL x
LOCAL nFreq
m.i = 0 && Index start position

m.x = SCR_EnumDisplaySettings( i ) && Enumerate all settings
DO WHILE ( m.x ) && While success

Screen Functions
m.szDevice = SCR_GetDMMember(1 ) && Device name
m.nBitsPerPixel = SCR_GetDMMember(22) && Bits
m.nFreq = SCR_GetDMMember(26) && Frequency
IF ( m.nFreq > 1 ) && If frequency is above 1 Hz

? m.szDevice , ; && Display the device name
m.nBitsPerPixel, ; && Display the number of bits per pixel
ALLTRIM( STR( m.nFreq ) ) + " Hz" && Display the supported frequency
ENDIF
m.i = m.i + 1 && Next Display Setting

m.x = SCR_EnumDisplaySettings(m.i) && Get values of the next setting
ENDDO
SCR_GetFullScreenDimensions() : Determines the usable

dimensions of the Windows desktop.
Remark
This function is similar (but not identical) to the SCR_rows() and SCR_cols() functions, but it does it in one pass.
Syntax
SCR_GetFullScreenDimensions( @iRows,@iCols )  lSuccess
Parameters
iRows number of Y pixels. MUST BE PASSED BY REFERENCE.
iCols number of X pixels. MUST BE PASSED BY REFERENCE.
Returns
SCR_GetScreenDimensions() : Determines the usable

dimensions of the Windows desktop.
Remark
This function is similar (but not identical) to the SPI_GetWorkArea() function: it retrieves the dimensions of the
Windows desktop area minus the space reserved for the system tray.
Syntax
SCR_GetScreenDimensions( @iRows,@iCols )  lSuccess
Parameters
iRows number of Y pixels. MUST BE PASSED BY REFERENCE.
iCols number of X pixels. MUST BE PASSED BY REFERENCE.
Returns

Screen Functions
SCR_LastVersion() : Returns the file stamp of SCR functions.
Remark
Syntax
SCR_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\SCR.C-Mon Oct 19 15:55:22 1998" .
SCR_MinimumDragHeight() : Minimum tracking height of a

window.
Alias
SYS_MinimumDragHeight()
Comment
The user cannot drag the window's frame to a size smaller than this dimension.
Syntax
SCR_MinimumDragHeight()  nPixels
Parameters
None.
Returns
nPixels number of pixels.
SCR_MinimumDragWidth() : Minimum tracking width of a

window.
Alias
SYS_MinimumDragWidth()
Comment
The user cannot drag the window’s frame to a size smaller than this dimension. A form cannot be resized to a smaller
dimension than the return value of this function. However, the SCR_MinimumDragWidth() takes the width of the

Screen Functions
sizable window frame in account: SCR_MinimumDragWidth() – ( 2 * SYSMETRIC(3) ) = Minimum form
width.
Syntax
SCR_MinimumDragWidth()  nPixels
Parameters
None.
Returns
SCR_RefreshDisplay() : Refreshes the entire display.

Syntax
SCR_RefreshDisplay()  .T.
Parameters
None.
Returns
SCR_ResetDisplaySettings() : Returns to the default mode

display.
Syntax
SCR_ResetDisplaySettings()  iRetVal
Parameters
None.
Returns
iRetVal The function returns one of the following values:
DISP_CHANGE_SUCCESSFUL 0
DISP_CHANGE_RESTART 1
DISP_CHANGE_FAILED -1
DISP_CHANGE_BADMODE -2
DISP_CHANGE_NOTUPDATED -3
DISP_CHANGE_BADFLAGS -4
DISP_CHANGE_BADPARAM -5
Example
SCR_ResetDisplaySettings()
? SCR_LastError()

Screen Functions
SCR_roloc() : Reverses color attribute
Comment
This function reverses the color attribute; that is the foreground becomes the background and vice versa. Please notice
that the high intensity bit becomes the blinking bit and vice versa.
Syntax
SCR_roloc( nColor )  nRevert
Parameters
nColor color attribute (see appendix A).
Returns
nRevert reverted color.
Example
* This example turns the color 135 (W/N*) into 120 (N+/W)
? SCR_roloc( 135 ) && 120

Shell Functions
Shell Functions

Shell Functions
Functions Synopsis
Shell functions were first introduced in FOCUS.FLL 7.84. They requires some important update of the SHELL32.DLL
file. To get the most recent version of the Shell and Common Controls DLLs, download and install Internet Explorer
(http://www.microsoft.com/windows/IE).

Shell Functions
SHE_AddIcon() : Adds an icon in the System Tray of Windows.

Abstract
FOCUS.FLL contains several functions that help managing icons to be placed in the System Tray. For example, the
following icon has been placed in the tray thanks to the SHE_AddIcon() function.
FOCUS.FLL can handle up to 15 different icons. Here's the quick path to Tray Icons:
1) Use the SHE_AddIcon() function with 2 parameters: the icon filename and the Tooltip text
2) SHE_AddIcon() will return an icon number (starting from 0 to 14). Up to 15 icons can be placed in the tray
3) When you want to remove the icon, please use its number (returned by SHE_AddIcon() ) with the
SHE_DeleteIcon() function
4) Notifications of mouse events are sent to a customizable function. The function can be set using the
SHE_SetTrayIconProc() function. ALL icons trigger the same notification function. The function receives
two parameters: the icon number that fired the event and the event ID (to check to distinguish between mouse
moves, clicks, right-clicks).
5) Notifications will start being fired as soon as the SYS_HookWindowProc() is called.
6) Notification can be suspended with the SYS_UnHookWindowProc() function.
7) SHE_DeleteAllTrayIcons() will remove all icons set with FOCUS.FLL
8) SET LIBRARY TO will remove all icons set with FOCUS.FLL
Syntax
SHE_AddIcon( szIcon,szTooltip )  nIconID
Parameters
szIcon icon filename.
szTooltip tooltip to assign to the icon.
Returns
nCountID icon identification number (from 0 to 14). –1 if the icon hasn't been added.
Example
&& EXAMPLE #1
LOCAL szIcon
LOCAL nIcon
IF ( SHE_IconsFree() > 0 )
m.szIcon = "D:\Microsoft Visual Studio\Common\Graphics\icons\computer\w95mbx02.ico"
m.nIcon = SHE_AddIcon( m.szIcon,"Hello from FastWrite" )
IF ( m.nIcon != -1 )
? "Icon successfully added to the Tray Notification Area"
ENDIF
ENDIF
&& EXAMPLE #2
&& Here's a full example in pure interactive mode:
&& It adds 6 times the same icon to the System Tray

Shell Functions
&& with different tooltips
&& When the mouse hovers the icons, the HereWeGo()
&& function is executed: the icon identification
&& number is passed to the function by FOCUS.FLL
set libr to focus
? SHE_AddIcon( m.szIcon,"Hello from FastWrite" ) && Icon #1

? SHE_AddIcon( m.szIcon,TTOC( DATETIME() ) ) && Icon #2
? SHE_AddIcon( m.szIcon,"Hello from LOGOS" ) && Icon #3
? SHE_AddIcon( m.szIcon,"Hello from Bob" ) && Icon #5
? SHE_SetTrayIconProc( "HereWeGo" )
? SYS_HookWindowProc()
set proc to myproc additive
*********************************
* Put this function in MYPROC.PRG
*********************************
FUNCTION HereWeGo( n,x )
WAIT WINDOW "Icon #" + ALLTRIM(STR(n)) NOWAIT
RETURN ( .NULL. )
SHE_CopyFile() : Copies multiple source files from one

location to another.
Remark
The SHE_CopyFile() function makes intensive use of the SHFileOperation() function of the Shell of Windows.
Therefore all remarks that do apply to SHFileOperation() are also applicable to SHE_CopyFile() .
Unlike many functions of the Windows API, the SHFileOperation() does not perform a given operation on files
whose names have been passed as parameters to the function. Instead, the action to perform is a parameter in itself
which gives the Visual FoxPro developer with somewhat troubles. The SH_CopyFile() function solves this difficulty
by automatically preparing the parameters you need.
The SHFileOperation() function can perform many tasks such as copying files, deleting files, moving and
renaming files. Of course, here we're concentrated on the copy operation.
To move or copy files from one location to another we need to specify:
 a string containing the source file names. This can be a sequence of files, a single name, wildcards, or even a
sequence of wildcards.
 a string containing a directory name. If we're moving or copying a well-defined list of files, then this string needs
to be a list of names, taking care to preserve a 1:1 correspondence with the source names which basically means
that each source file name should be matched by a target file name.
Each file name must be separated by the next one with a NULL ( CHR(0) ). The function expects a double
NULL (CHR(0) + CHR(0) ) at the end of the string passed (this is true even if you pass a single file name or
a single wildcard). If you do not include a double NULL at the end of the string, then the function might
work or not. This is applicable for the szSource parameter of SHE_CopyFile() and for szTarget if this
one contains more than one file name.
Because FOCUS.FLL greatly simplifies the interface of the Shell API it uses a set of default behaviors that are
otherwise all triggered via parameters:
1. No error message will be displayed because all dialog have been suppressed; instead, the function will return
.T. or .F. ,

Shell Functions
2. If a subdirectory needs to be created, it will be created automatically. That means that will be no dialog to
confirm the creation of a subdirectory,
3. In case of name collisions, the files are duplicated by assigning them new names (THEY ARE NOT
OVERWRITTEN!)
4. Multiple destination files are supported.
Even though supported, at this time we cannot fully assure you that copying entire directories will work
smoothly and seamlessly. This function needs more testing cycles even if we have made every effort to
ensure its accuracy.
Alias
SHE_CopyFiles(), SHCopyFiles()
Syntax
SHE_CopyFiles( szSource,szTarget )  lSuccess
Parameters
szSource source files such as "D:\INVOICES\*.*". Don't forget to use double NULL to terminate the
string.
szTarget target files or simply a directory under which files should be recopied (please notice that the
target directory MUST exist prior to calling the SHE_CopyFile() function).
Returns
Example
&& "O:\MYCOPY" MUST exist for the function to be successful!
? SHE_CopyFile( "D:\INVOICES\*.*" + CHR(0) + CHR(0),"O:\MYCOPY" )
... will produce the following dialog to be displayed. Please notice that all sub-directories will be automatically created!
SHE_DeleteAllTrayIcons() : Removes all icons set with

SHE_AddIcon().
Abstract

Shell Functions
FOCUS.FLL can handle up to 15 different icons. Please notice that FOCUS.FLL cannot remove icons placed by
other processes.
Syntax
SHE_DeleteAllTrayIcons()  .T.
Parameters
None.
Returns
.T. Always.
SHE_DeleteIcon() : Removes an icon from the System Tray of

Windows.
Abstract
FOCUS.FLL can handle up to 15 different icons. Please notice that FOCUS.FLL cannot remove icons placed by
other processes.
Syntax
SHE_DeleteIcon( nIcon )  lSuccess
Parameters
nIcon icon identification number.
Returns
Example
LOCAL szIcon
LOCAL nIcon
? "Icon successfully added to the Tray Notification Area. Let's remove it now"
WAIT WINDOW "Press ENTER"
IF ( SHE_DeleteIcon( m.nIcon ) )
? "The icon is removed now!"
ELSE
? "The icon hasn't been removed",SHE_LastError()
ENDIF
ENDIF
ENDIF

Shell Functions
SHE_GetDllVersion() : Obtains version information from the
shell32.dll.
Alias
SHGetDllVersion()
Syntax
SHE_GetDllVersion( nInfo )  nVersionInfo
Parameters
nInfo the member to obtain information for:
Value Description
1 Major number
2 Minor number
3 Build number
4 Platform ID
#define DLLVER_PLATFORM_WINDOWS 0x00000001 // Windows 95/98
#define DLLVER_PLATFORM_NT 0x00000002 // Windows NT
Any other Major number
numeric
value
Returns
nVersionInfo the version info that was queried. -1 if the DLL couldn't be opened. -2 if the version info
couldn't be obtained.
Example
? SHE_GetDllversion( 1 ) // 4
See also
SYS_GetDllVersion()
SHE_GetIconCount() : Get the number of icons found in an

executable, or .DLL.
Syntax
SHE_GetIconCount( szFile )  n
Parameters
szFile file from which the number of icons must be returned.
Returns
n icon count or –1 in case of error.
Example
szFile = " FOCUS.FLL"
? SHE_GetIconCount( szFile ) && Should display 2

Shell Functions
SHE_IconsFree() : Determines how many icons can still be
placed in the System Tray of Windows.
Abstract
Syntax
SHE_IconsFree()  nCount
Parameters
None
Returns
nCount number of icons free (from 0 to 15).
Example
LOCAL szIcon
LOCAL nIcon
? "Icon successfully added to the Tray Notification Area"
ENDIF
ENDIF
SHE_IsActiveDesktopInstalled() : Checks for the Active

Desktop.
Alias
SHIsActiveDesktopInstalled(), IsActiveDesktopInstalled(),SYS_IsActiveDesktopInstalled()
Syntax
SHE_IsActiveDesktopInstalled()  lInstalled
Parameters
None
Returns
lInstalled .T. if Active Desktop is installed; .F. otherwise.
Example
IF ( SHE_IsActiveDesktopInstalled() )
? "Active Desktop is installed"
ENDIF

Shell Functions
SHE_LastError() : Returns the last error that occurred in the
SHE_*() functions.
Syntax
SHE_LastError()  szLastError
Parameters
None.
Returns
szLastError last error
SHE_LastVersion() : Returns the file stamp of SHE functions.

Remark
Syntax
SHE_LastVersion()  szLastVersion
Parameters
None.
Returns
"D:\Focus\6.0\Shell.c-Thu Jul 20 21:42:48 2000".
SHE_QueryRecycleBin() : Determines the number of deleted

items in the recycle bin of a specific drive.
Syntax
SHE_QueryRecycleBin( szDrive )  nItems
Parameters
szDrive drive string such as "D:\".
Returns
nItems number of items in given recycle bin. 0 indicates that there is no deleted item available in the
recycle bin; -1 indicates that there was an error trying to access the specific recycle bin; -2
indicates that shell32.dll does not support the requested feature.
Example
LOCAL nItems
nItems = SHE_QueryRecycleBin( "C:\" )

Shell Functions
IF ( nItems >= 0 )
IF ( nItems > 0 )
? "There are",nItems,"items in the Recycle Bin"
ELSE
? "The Recycle Bin is empty"
ENDIF
ELSE
? "There was an error accessing the Recycle Bin"
ENDIF
SHE_PathAddBackslash() : Adds a backslash to the end of a

path.
Syntax
SHE_PathAddBackslash( szDir )  szNewDir
Parameters
szDir path to which to add the backslash.
Returns
szNewDir path with added backslash.
Example
? SHE_PathAddBackslash( "D:\MYDIR\MYOTHERDIR" ) && "D:\MYDIR\MYOTHERDIR\"
See also
SYS_PathRemoveBackslash()
SHE_PathCompact() : Truncates a path to fit within a certain

number of characters by replacing path components with
ellipses.
Syntax
SHE_PathCompact( szDir,nChars )  szDirEllipses
Parameters
szDir path to alter.
nChars maximum number of characters to be contained in the new path.
Returns
szDirEllipses the altered path.
Example
? SHE_PathCompact( "c:\mydir\theOtherDir\myfile.txt",25 ) && "c:\mydir\th...\myfile.txt"
SHE_PathIsRelative() : Searches a path and determines if it is

relative.
Syntax
SHE_PathIsRelative( szDir )  lIsRelative

Shell Functions
Parameters
szDir path to be validated.
Returns
lIsRelative .T. if szDir is a relative resource; .F. if not.
Example
? SHE_PathIsRelative( "D:\MYDIR\MYOTHERDIR" ) && .F.
? SHE_PathIsRelative( "C:\" ) && .F.
? SHE_PathIsRelative( "D:\" ) && .F.
? SHE_PathIsRelative( "\\orion\d" ) && .F.
? SHE_PathIsRelative( "..\test" ) && .T.
? SHE_PathIsRelative( "test.exe" ) && .T.
? SHE_PathIsRelative( ".\test.exe" ) && .T.
? SHE_PathIsRelative( ".\" ) && .T.
See also
SYS_PathIsRoot()
SHE_PathIsRoot() : Parses a path to determine if it is a

directory root.
Syntax
SHE_PathIsRoot( szDir )  lIsRoot
Parameters
szDir path to be validated.
Returns
lIsRoot .T. if szDir is a root directory; .F. if not.
Example
? SHE_PathIsRoot( "D:\MYDIR\MYOTHERDIR" ) && .F.
? SHE_PathIsRoot( "C:\" ) && .T.
? SHE_PathIsRoot( "D:\" ) && .T.
? SHE_PathIsRoot( "\\orion\d" ) && .T.
See also
SYS_PathIsRelative()
SHE_PathIsUNC() : Determines if the string is a valid UNC

(universal naming convention) for a server and share
path.
Aliases
FIL_isUNC()
Syntax
SHE_PathIsUNC( szPath )  lIsUNC
Parameters

Shell Functions
Returns
lIsUNC .T. if szPath is a valid UNC path; .F. otherwise.
Example
? SHE_PathIsUNC( "\\orion" ) && .T.
? SHE_PathIsUNC( "\\orion\" ) && .T.
? SHE_PathIsUNC( "\\orion\d" ) && .T.
? SHE_PathIsUNC( "\\orion\d\mydir" ) && .T.
? SHE_PathIsUNC( "y:\mydir" ) && .F.
SHE_PathIsUNCServer() : Determines if a string is a valid UNC

for a server path only.
Syntax
SHE_PathIsUNCServer( szPath )  lIsUNCServer
Parameters
Returns
lIsUNCServer .T. if szPath is a valid UNC server path; .F. otherwise.
Example
? SHE_PathIsUNCServer( "\\orion" ) && .T.
? SHE_PathIsUNCServer( "\\orion\d" ) && .F.
SHE_PathIsUNCServerShare() : Determines if a string is a valid

UNC share path, \\server\share.
Syntax
SHE_PathIsUNCServerShare( szPath )  lIsUNCServerShare
Parameters
Returns
lIsUNCServerShare .T. if szPath is a valid UNC server share path; .F. otherwise.
Example
? SHE_PathIsUNCServerShare( "\\orion" ) && .F.
? SHE_PathIsUNCServerShare( "\\orion\d" ) && .T.
SHE_PathIsURL() : Tests a given string to determine if it

conforms to a valid URL format.
Syntax
SHE_PathIsURL( szPath )  lIsURL

Shell Functions
Parameters
szPath URL path to validate.
Returns
lIsURL .T. if szDir is a URL path; .F. if not.
Example
? SHE_PathIsURL( "http://www.fastwrite.com/products/" ) && .T.
? SHE_PathIsURL( "://www.fastwrite.com/products/" ) && .F.
? SHE_PathIsURL( "www.fastwrite.com" ) && .F.
? SHE_PathIsURL( " fastwrite.com" ) && .F.
? SHE_PathIsURL( "htt://www.fastwrite.com/products/" ) && .T.
? SHE_PathIsURL( "ht://www.fastwrite.com/products/" ) && .T.
? SHE_PathIsURL( "h://www.fastwrite.com/products/" ) && .F.
? SHE_PathIsURL( "ftp://www.fastwrite.com/products/" ) && .T.
SHE_PathRemoveBackslash() : Removes the trailing

backslash from a given path.
Syntax
SHE_PathRemoveBackslash( szDir )  szNewDir
Parameters
szDir path from which to remove the backslash.
Returns
szNewDir path with removed backslash.
Example
? SHE_PathRemoveBackslash( "D:\MYDIR\MYOTHERDIR\" ) && "D:\MYDIR\MYOTHERDIR"
See also
SYS_PathAddBackslash()

Sizeof Functions
Sizeof Functions

Sizeof Functions
SIZ_bool() : Size of a bool.

Syntax
SIZ_bool()  nSize
Parameters
None.
Returns
nSize size of the corresponding data type.
SIZ_char() : Size of a char.

Syntax
SIZ_char()  nSize
Parameters
None.
Returns
SIZ_double() : Size of a double.

Syntax
SIZ_Double()  nSize
Parameters
None.
Returns
SIZ_dword() : Size of a DWORD.

Syntax
SIZ_dword()  nSize
Parameters
None.
Returns

Sizeof Functions
SIZ_enum() : Size of an enum.
Syntax
SIZ_enum()  nSize
Parameters
None.
Returns
SIZ_float() : Size of a float.

Syntax
SIZ_float()  nSize
Parameters
None.
Returns
SIZ_int() : Size of an integer.

Syntax
SIZ_int()  nSize
Parameters
None.
Returns
SIZ_int8() : Size of a 8-bit integer.

Syntax
SIZ_int8()  nSize
Parameters
None.
Returns
nSize size of the corresponding data type. Obviously, this function should return 1.

Sizeof Functions
Syntax
Parameters
None.
Returns

Syntax
Parameters
None.
Returns

Syntax
Parameters
None.
Returns
nSize size of the corresponding data type. Currency data type in Visual FoxPro corresponds to a large
integer (int64). Obviously, this function should return 8.
SIZ_handle() : Size of a handle.

Syntax
SIZ_handle()  nSize
Parameters
None.
Returns

Sizeof Functions
SIZ_hwnd() : Size of a window handle (HWND).
Syntax
SIZ_hwnd()  nSize
Parameters
None.
Returns
SIZ_LastVersion() : Returns the file stamp of the SIZ functions.

Remark
Syntax
SIZ_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\SIZEOF.C-Mon Oct 19 15:55:22 1999" .
SIZ_long() : Size of a long.

Syntax
SIZ_Long()  nSize
Parameters
None.
Returns
SIZ_longdouble() : Size of a long double.

Syntax
SIZ_LongDouble()  nSize
Parameters
None.
Sizeof Functions
Returns
SIZ_short() : Size of a short.

Syntax
SIZ_short()  nSize
Parameters
None.
Returns
SIZ_tchar() : Size of a TCHAR.

Syntax
SIZ_tchar()  nSize
Parameters
None.
Returns
SIZ_uint() : Size of an unsigned integer.

Syntax
SIZ_uint()  nSize
Parameters
None.
Returns
SIZ_wchar() : Size of a WCHAR.

Syntax
SIZ_wchar()  nSize
Parameters
None.

Sizeof Functions
Returns
SIZ_whandle() : Size of a window handle (WHANDLE)

Syntax
SIZ_whandle()  nSize
Parameters
None.
Returns

Sound Functions
Sound Functions

Sound Functions
SND_AppEvent() : Plays a waveform identified by an entry in

the registry.
Syntax
SND_AppEvent( szApplication,szEvent )  lSuccess
Parameters
szApplication the application name as stored in the Windows registry.
szEvent the event whose sound should be played back.
As the above screen capture suggests, the Application Name must appear under the following
key : HKEY_CURRENT_USER\AppEvents\Schemes\Apps .
Returns
lSuccess .T.. if the sound was found and successfully played; .F. otherwise.
Example
SND_AppEvent( "FOCUS","FOCUSLoading" )
SND_asterisk() : Plays a waveform identified by an entry in the

registry (iconasterisk)
Syntax
SND_asterisk()  .T.
Parameters
None.

Sound Functions
Returns
SND_error() : Plays a waveform identified by an entry in the

registry (iconhand)
Syntax
SND_error()  .T.
Parameters
None.
Returns
SND_exclamation() : Plays a waveform identified by an entry in

the registry (iconexclamation)
Syntax
SND_exclamation()  .T.
Parameters
None.
Returns
SND_LastVersion() : Returns the file stamp of SND functions.

Remark
Syntax
SND_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\SOUND.C-Mon Oct 19 15:55:22 1998" .

Sound Functions
SND_OK() : Plays a waveform identified by an entry in the
registry (iconok)
Syntax
SND_OK()  .T.
Parameters
None.
Returns
SND_play() : Plays a waveform sound specified by a filename.

Comment
The directories searched for sound files are, in order: the current directory; the Windows directory; the Windows
system directory; the directories listed in the PATH environment variable; the list of directories mapped in a network.
Syntax
SND_play( szFile[,nType] )  lSuccess
Parameters
szFile the name of the sound to play. The function searches the name section of WIN.INI for an
entry with this name and plays the associated waveform file. If no entry by this name exists,
then it assumes the name is the name of a waveform file. If this parameter is NULL( ""), any
currently playing sound is stopped.
nType options for playing the sound using one or more of the following flags. Optional: 0 by default:
Value Description
0 plays the sound file synchronously. The function does not return until the sound
ends.
1 plays the sound file asynchronously. The function returns immediately after
beginning the sound. To terminate an asynchronously-played sound, call
sndPlaySound() with szFile set to NULL.
Returns
lSuccess .T. if sound played; .F. if not.
Example
SND_play( "Banner",1 ) && Plays musical theme
SND_repeat() : Repeats the last waveform that was played.

Syntax
SND_repeat()  .T.
Parameters
None.

Sound Functions
Returns
Example
SND_play( "Banner" ) && Plays musical theme
SND_repeat() && Replay
SND_Standard() : Standard beep using the computer speaker.

Syntax
SND_Standard()  .T.
Parameters
None.
Returns
SND_Stop() : Stops playing any wave file.

Syntax
SND_Stop()  .T.
Parameters
None.
Returns
SND_vers() : Returns the FOCUS Sound version.

Syntax
SND_vers()  szVers
Parameters
None.
Returns
szVers version of SOUND module of FOCUS.

SPI Functions
System Parameters Info Functions

SPI Functions
Functions Synopsis
SPI_*() functions are all based on SystemParametersInfo() function of the Windows SDK. Given the fact that
this function uses data types that do not exist in Visual FoxPro, we found it useful to provide these services to you.
The SystemParametersInfo() function queries or sets system-wide parameters. This function can also update the
user profile while setting a parameter.
One of my favorites is the ability to setup the Windows Wallpaper easily. You’ll also notice that it is possible to change
keyboard delay and keyboard speed.
Following is a table of all SystemParametersInfo() values you can query or set. In order to have the most
accurate information we could provide, we slightly adapted the Microsoft Visual C++ help.
VALUE Meaning
SPI_GETACCESSTIMEOUT Retrieves information about the time-out period associated with the
accessibility features. The wParam parameter specifies the size of an
ACCESSTIMEOUT structure, and pvParam is the address of the
ACCESSTIMEOUT structure that receives the information.
SPI_GETBEEP Determines whether the warning beeper is on ( TRUE ) or off (FALSE ). The
pvParam parameter points to a BOOL variable.
SPI_GETBORDER Retrieves the border multiplier factor that determines the width of a
window's sizing border. The pvParam parameter points to an integer
variable.
SPI_GETFASTTASKSWITCH Determines whether fast task switching is enabled. The pvParam parameter
points to a BOOL variable that receives TRUE if enabled, or FALSE
otherwise.
SPI_GETFILTERKEYS Retrieves information about the FilterKeys accessibility feature. The wParam
parameter specifies the size of the FILTERKEYS structure, and pvParam is
the address of the FILTERKEYS structure that receives the information.
SPI_GETGRIDGRANULARITY Retrieves the current granularity value of the desktop sizing grid. The
pvParam parameter points to an integer variable that receives the
granularity.
SPI_GETICONTITLELOGFONT Retrieves the logical font information for the current icon-title font. The
wParam parameter specifies the size of a LOGFONT structure, and the
pvParam parameter points to the LOGFONT structure to fill in.
SPI_GETICONTITLEWRAP Determines whether icon-title wrapping is enabled. The pvParam parameter
otherwise.
SPI_GETKEYBOARDDELAY Retrieves the keyboard repeat-delay setting. The pvParam parameter
points to an integer variable that receives the setting.
SPI_GETKEYBOARDSPEED Retrieves the keyboard repeat-speed setting. The pvParam parameter
points to a DWORD variable that receives the setting.
SPI_GETMENUDROPALIGNMENT Determines whether pop-up menus are left aligned or right aligned, relative
to the corresponding menu-bar item. The pvParam parameter points to a
BOOL variable that receives TRUE if left-aligned, or FALSE otherwise.
SPI_GETMOUSE Retrieves the mouse thresholds and speed. The pvParam parameter points
to an array of three integers that receive the x-threshold, the y-threshold,
and the speed.
SPI_GETMOUSEKEYS Retrieves information about the MouseKeys accessibility feature. The
wParam parameter specifies the size of a MOUSEKEYS structure, and
pvParam is the address of the MOUSEKEYS structure that receives the
information.
SPI_GETSCREENSAVEACTIVE Determines whether screen saving is enabled. The pvParam parameter
otherwise.
SPI_GETSCREENSAVETIMEOUT Retrieves the screen saver time-out value, in milliseconds. The pvParam
parameter points to an integer variable that receives the value.
SPI_GETSHOWSOUNDS Determines whether the user requires an application to present information

SPI Functions
visually in situations where it would otherwise present the information only
in audible form. The wParam parameter points to a BOOL variable. Using
this value is equivalent to calling
GetSystemMetrics(SM_GETSHOWSOUNDS) . That is the recommended
call.
SPI_GETSOUNDSENTRY Retrieves information about the SoundSentry accessibility feature. The
wParam parameter specifies the size of a SOUNDSENTRY structure, and
pvParam is the address of the SOUNDSENTRY structure that receives the
information.
SPI_GETSTICKYKEYS Retrieves information about the MouseKeys accessibility feature. The
wParam parameter specifies the size of a STICKYKEYS structure, and
pvParam is the address of the STICKYKEYS structure that receives the
information.
SPI_GETTOGGLEKEYS Retrieves information about the ToggleKeys accessibility feature. The
wParam parameter specifies the size of a TOGGLEKEYS structure, and
pvParam is the address of the TOGGLEKEYS structure that receives the
information.
SPI_ICONHORIZONTALSPACING Sets the width of an icon cell. The wParam parameter specifies the width, in
pixels.
SPI_ICONVERTICALSPACING Sets the height of an icon cell. The wParam parameter specifies the height,
in pixels.
SPI_LANGDRIVER Identifies the language driver. The pvParam parameter points to a
character array that receives the filename of the language driver.
SPI_SETACCESSTIMEOUT Sets the time-out period associated with the accessibility features. The
wParam parameter specifies the size of the ACCESSTIMEOUT structure, and
pvParam is the address of the ACCESSTIMEOUT structure that contains the
new parameters.
SPI_SETBEEP Turns the warning beeper on or off. The wParam parameter specifies TRUE
for on, or FALSE for off.
SPI_SETBORDER Sets the border multiplier factor that determines the width of a window's
sizing border. The wParam parameter specifies the new value.
SPI_SETDESKPATTERN Sets the current desktop pattern by causing Windows to read the
Pattern= setting from the WIN.INI file.
SPI_SETDESKWALLPAPER Sets the desktop wallpaper. The pvParam parameter points to a null-
terminated string containing the name of a bitmap file.
SPI_SETDOUBLECLICKTIME Sets the double-click time for the mouse to the value of the wParam
parameter. The double-click time is the maximum number of milliseconds
that can occur between the first and second clicks of a double-click.
SPI_SETDOUBLECLKHEIGHT Sets the height of the double-click rectangle to the value of the wParam
parameter. The double-click rectangle is the rectangle within which the
second click of a double-click must fall for it to be registered as a double-
click.
SPI_SETDOUBLECLKWIDTH Sets the width of the double-click rectangle to the value of the wParam
parameter. The double-click rectangle is the rectangle within which the
second click of a double-click must fall for it to be registered as a double-
click.
SPI_SETFASTTASKSWITCH Turns fast task switching on or off. The wParam parameter specifies TRUE
SPI_SETFILTERKEYS Sets the parameters of the FilterKeys accessibility feature. The wParam
parameter specifies the size of the FILTERKEYS structure, and pvParam is
the address of the FILTERKEYS structure that contains the new
parameters.
SPI_SETGRIDGRANULARITY Sets the granularity of the desktop sizing grid to the value of the wParam
parameter.
SPI_SETICONTITLELOGFONT Sets the font that is used for icon titles. The wParam parameter specifies
the size of a LOGFONT structure, and the lParam parameter points to a
LOGFONT structure.
SPI_SETICONTITLEWRAP Turns icon-title wrapping on or off. The wParam parameter specifies TRUE
SPI_SETKEYBOARDDELAY Sets the keyboard repeat-delay setting to the value of the wParam
parameter.
SPI_SETKEYBOARDSPEED Sets the keyboard repeat-speed setting to the value of the wParam
parameter.
SPI_SETMENUDROPALIGNMENT Sets the alignment value of pop-up menus. The wParam parameter
specifies TRUE for right alignment, or FALSE for left alignment.
SPI_SETMOUSE Sets the mouse thresholds and speed. The pvParam parameter points to an

SPI Functions
array of three integers that specifies the x-threshold, the y-threshold, and
the speed.
SPI_SETMOUSEBUTTONSWAP Swaps or restores the meaning of the left and right mouse buttons. The
wParam parameter specifies TRUE to swap the meanings of the buttons, or
FALSE to restore their original meanings.
SPI_SETMOUSEKEYS Sets the parameters of the MouseKeys accessibility feature. The wParam
parameter specifies the size of the MOUSEKEYS structure, and pvParam is
the address of the MOUSEKEYS structure that contains the new parameters.
SPI_SETSCREENSAVEACTIVE Sets the state of the screen saver. The wParam parameter specifies TRUE
to activate screen saving, or FALSE to deactivate it.
SPI_SETSCREENSAVETIMEOUT Sets the screen saver time-out value to the value of the wParam
parameter. This value is the amount of time, in milliseconds, that the
system must be idle before the screen saver activates.
SPI_SETSHOWSOUNDS Sets the ShowSounds accessibility feature as on or off. The wParam
parameter specifies TRUE for on, or FALSE for off.
SPI_SETSOUNDSENTRY Sets the parameters of the SoundSentry accessibility feature. The wParam
parameter specifies the size of the SOUNDSENTRY structure, and pvParam
is the address of the SOUNDSENTRY structure that contains the new
parameters.
SPI_SETSTICKYKEYS Sets the parameters of the StickyKeys accessibility feature. The wParam
parameter specifies the size of the STICKYKEYS structure, and pvParam is
the address of the STICKYKEYS structure that contains the new
parameters.
SPI_SETTOGGLEKEYS Sets the parameters of the ToggleKeys accessibility feature. The wParam
parameter specifies the size of the TOGGLEKEYS structure, and pvParam is
the address of the TOGGLEKEYS structure that contains the new
parameters.
Many SPI settings can be found in the WIN.INI file :
[windows]
load=C:\WINDOWS\POINTER.EXE C:\MOUSE\POINTER.EXE
run=C:\WINDOWS\WSIZER.EXE
Beep=yes
NullPort=None
BorderWidth=3
CursorBlinkRate=530
DoubleClickSpeed=452
Programs=com exe bat pif
Documents=
KeyboardDelay=0
KeyboardSpeed=31
ScreenSaveActive=0
ScreenSaveTimeOut=120
MouseThreshold1=0
MouseThreshold2=0
MouseSpeed=0
device=Epson EPL-5600,HPPCL5MS,LPT1:
[Desktop]
Pattern=(aucun)
TileWallPaper=1
GridGranularity=5
Wallpaper=D:\CSERVE\DOWNLOAD\WIN95.BMP
WallpaperStyle=0

SPI Functions
SPI_GetBeep() : Determines whether the warning beeper is on.

Syntax
SPI_GetBeep()  lIsBeepOn
Parameters
None.
Returns
lIsBeepOn .T. when warning beep on; .F. otherwise.
SPI_GetBorder() : Retrieves the border multiplier factor that

determines the width of a window's sizing border.
Syntax
SPI_GetBorder()  nBorder
Parameters
None.
Returns
nBorder border multiplier factor.
SPI_GetDoubleClickHeight() : Height in pixels of the double-

click rectangle.
Remark
Height, in pixels, of the rectangle around the location of a first click in a double-click sequence. The second click must
occur within this rectangle for the system to consider the two clicks a double-click.
Alias
GetDoubleClickHeight(), SYS_GetDoubleClickHeight()
Syntax
SPI_GetDoubleClickHeight()  nHeight
Parameters
None.
Returns
nHeight current height in pixels of the rectangle in which the double click should occur.

SPI Functions
SPI_GetDoubleClickTime() : Retrieves the current double-click
time for the mouse.
Remark
A double-click is a series of two clicks of the mouse button, the second occurring within a specified time after the first.
The double-click time is the maximum number of milliseconds that may occur between the first and second click of a
double-click. Unlike the _DBLCLICK internal variable of Visual FoxPro, the SPI_GetDoubleClickTime() function
always retrieves the current value of the Windows Mouse Control Panel.
Alias
GetDoubleClickTime(), SYS_GetDoubleClickTime()
Syntax
SPI_GetDoubleClickTime()  nMilliSeconds
Parameters
None.
Returns
nMilliSeconds current double-click time, in milliseconds.
SPI_GetDoubleClickWidth() : Width in pixels of the double-

click rectangle.
Remark
Width, in pixels, of the rectangle around the location of a first click in a double-click sequence. The second click must
Alias
GetDoubleClickHeight(), SYS_GetDoubleClickHeight()
Syntax
SPI_GetDoubleClickHeight()  nHeight
Parameters
None.
Returns
nHeight current width in pixels of the rectangle in which the double click should occur.
SPI_GetFastTaskSwitch() : Is Alt-Tab enabled?

Remark
This flag is obsolete. Previous versions of Windows use this flag to determine whether ALT+TAB fast task switching is
enabled. Beginning with Windows 95 and Windows NT version 4.0, fast task switching is always enabled
Syntax
SPI_GetFastTaskSwitch()  lAltTab

SPI Functions
Parameters
None.
Returns
lAltTab Alt-Tab fast task switching allowed (.T. ) or not (.F. ).
SPI_GetGrid() : Retrieves the current granularity value of the

desktop sizing grid.
Syntax
SPI_GetGrid()  nGranularity
Parameters
None.
Returns
nGranularity current granularity value.
SPI_GetIconTitleWrap() : Determines whether icon-title

wrapping is enabled.
Syntax
SPI_GetIconTitleWrap()  lIconWrapping
Parameters
None.
Returns
lIconWrapping .T. if icon-title wrapping is ON; .F. otherwise.
SPI_GetKeyboardDelay() : Retrieves the keyboard repeat-delay

setting.
Syntax
SPI_GetKeyboardDelay()  nDelay
Parameters
None.
Returns
nDelay keyboard repeat-delay.

SPI Functions
SPI_GetKeyboardSpeed() : Retrieves the keyboard repeat-
speed setting.
Syntax
SPI_GetKeyboardSpeed()  nSpeed
Parameters
None.
Returns
nSpeed keyboard repeat-speed.
SPI_GetLastError() : Returns the last error encountered when

using SPI_*() functions.
Alias
SPI_LastError()
Syntax
SPI_GetLastError()  szError
Parameters
None.
Returns
szError Last SPI error description.
SPI_GetMenuDropAlignment() : Determines whether pop-up

menus are left-aligned or right-aligned, relative to the
corresponding menu-bar item.
Syntax
SPI_GetMenuDropAlignment()  lLeftAligned
Parameters
None.
Returns
lLeftAligned .T. if left-aligned; .F. otherwise.

SPI Functions
SPI_GetScreenReader() : Determines whether a screen
reviewer utility is running.
Remark
This function only returns a meaningful value under Windows 95. A screen reviewer utility directs textual information
to an output device, such as a speech synthesizer or Braille display. When this flag is set, an application should provide
textual information in situations where it would otherwise present the information graphically.
Syntax
SPI_GetScreenReader()  lScreenReader
Parameters
None.
Returns
lScreenReader Determines whether a screen reviewer utility is running (.T. ) or not (.F. ).
SPI_GetScreenSaveActive() : Determines whether screen

saving is enabled.
Syntax
SPI_GetScreenSaveActive()  lScreenSaveActive
Parameters
None.
Returns
lScreenSaveActive .T. if screen save active; .F. otherwise.
SPI_GetScreenSaveTimeout() : Gets the screen saver time-out

value.
Syntax
SPI_GetScreenSaveTimeout()  nValue
Parameters
None.
Returns
nValue screen saver time-out value.
SPI_GetShowSounds() : Determines whether the Show

Sounds accessibility flag is on or off.
Syntax
SPI_GetShowSounds()  lShowSounds

SPI Functions
Parameters
None.
Returns
lShowSounds .T. if the user requires an application to present information visually in situations where it
would otherwise present the information only in audible form; .F. otherwise.
SPI_GetWorkArea() : Retrieves the size of the working area.

Remark
This function is not supported in Windows NT 4, Server or Workstation, but it is in Windows 2000 and in XP!
Syntax
SPI_GetWorkArea( [@nTop,@nLeft,@nBottom,@nRight] )  szArea
Parameters
nTop top of rectangle. If passed, it must be passed by reference.
nLeft left of rectangle. If passed, it must be passed by reference.
nBottom bottom of rectangle. If passed, it must be passed by reference.
nRight right of rectangle. If passed, it must be passed by reference.
Either you pass no parameter or you pass them all.
Returns
szArea gets the size of the working area. The working area is the portion of the screen not obscured by
the tray (taskbar). The coordinates of the working area rectangle are formatted according to the
following pattern : "t,l,b,r" (top, left, bottom, right). If the function wasn't successful, then
szArea is empty.
if nTop ,nLeft ,nBottom and nRight were passed, these values will be updated and the result
of SPI_GetWorkArea() can simply be ignored.
Example
&& This code can be invoked after the user has moved the window on the screen
&& What is here, is a check to avoid having windows that are outside the limits
&& of the desktop
LOCAL nTop
LOCAL nLeft
LOCAL nBottom
LOCAL nRight
WITH ThisForm
m.nTop = 0
m.nLeft = 0
m.nBottom = 0
m.nRight = 0
SPI_GetWorkArea( @nTop,@nLeft,@nBottom,@nRight )
&& Impossibility to hide the window at the bottom of the screen

IF ( .Top + .Height > m.nBottom )
.Top = m.nBottom - .Height
ENDIF

SPI Functions
&& Impossibility to hide the window at the top of the screen
IF ( .Top < 0 )
.Top = 0
ENDIF
&& Impossibility to hide the window at the rightmost side of the screen
IF ( .Left + .Width > m.nRight )
.Left = m.nRight - .Width
ENDIF
&& Impossibility to hide the window at the leftmost side of the screen
IF ( .Left < 0 )
.Left = 0
ENDIF
ENDWITH
SPI_LastVersion() : Returns the file stamp of SPI functions.

Remark
Syntax
SPI_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\SPI.C-Mon Oct 19 15:55:22 1998" .
SPI_SetBorder() : Sets the border multiplier factor that

determines the width of a window's sizing border.
Syntax
SPI_SetBorder( nBorder )  lSuccess
Parameters
nBorder border multiplier factor.
Returns
lSuccess .T. if function was successful, .F. otherwise.
SPI_SetBeep() : Turns the warning beeper on or off.

Syntax
SPI_SetBeep( lSetting )  lSucess

SPI Functions
Parameters
lSetting .T. to turn the warning beep ON;.F. to turn it off.
Returns
SPI_SetDoubleClickHeight() : Height in pixels of the double-

click rectangle.
Remark
Height, in pixels, of the rectangle around the location of a first click in a double-click sequence. The second click must
Alias
SetDoubleClickHeight(), SYS_SetDoubleClickHeight()
Syntax
SPI_SetDoubleClickHeight( nHeight )  lSuccess
Parameters
nHeight height in pixels of the rectangle in which the double click should occur.
Returns
SPI_GetDoubleClickTime() : Sets the current double-click time

for the mouse.
Remark
A double-click is a series of two clicks of the mouse button, the second occurring within a specified time after the first.
The double-click time is the maximum number of milliseconds that may occur between the first and second click of a
double-click. Unlike the _DBLCLICK internal variable of Visual FoxPro, the SPI_SetDoubleClickTime() function
always influences the current value of the Windows Mouse Control Panel.
Alias
SetDoubleClickTime(), SYS_SetDoubleClickTime()
Syntax
SPI_SetDoubleClickTime( nMilliSeconds ) 
Parameters
nMilliSeconds double-click time, in milliseconds.
Returns

SPI Functions
SPI_SetDoubleClickWidth() : Width in pixels of the double-
click rectangle.
Remark
Width, in pixels, of the rectangle around the location of a first click in a double-click sequence. The second click must
Alias
SetDoubleClickHeight(), SYS_SetDoubleClickHeight()
Syntax
SPI_GetDoubleClickHeight( nHeight )  lSuccess
Parameters
nHeight width in pixels of the rectangle in which the double click should occur.
Returns
SPI_SetFastTaskSwitch() : Enables or disables Alt-Tab.

Remark
This flag is obsolete. Previous versions of Windows use this flag to determine whether ALT+TAB fast task switching is
enabled. Beginning with Windows 95 and Windows NT version 4.0, fast task switching is always enabled
Syntax
SPI_SetFastTaskSwitch( lAltTab )  lSuccess
Parameters
lAltTab Alt-Tab fast task switching allowed (.T. ) or not (.F. ).
Returns
SPI_SetGrid() : Sets the granularity of the desktop sizing grid.

Syntax
SPI_SetGrid( nGranularity ) lSuccess
Parameters
nGranularity new granularity of the desktop sizing grid.
Returns

SPI Functions
SPI_SetIconHorizontalSpacing() : Sets the width of an icon
cell.
Syntax
SPI_SetIconHorizontalSpacing( nSpacing )  lSucess
Parameters
nSpacing width of an icon cell.
Returns
SPI_SetIconTitleWrap() : Enables or disables icon-title

wrapping.
Syntax
SPI_SetIconTitleWrap( lIconWrapping )  lSuccess
Parameters
lIconWrapping .T. if icon-title wrapping is ON; .F. otherwise.
Returns
SPI_SetIconVeriticalSpacing() : Sets the height of an icon cell.

Syntax
SPI_SetIconVerticalSpacing( nSpacing )  lSucess
Parameters
nSpacing height of an icon cell.
Returns
SPI_SetKeyboardDelay() : Sets the keyboard repeat-delay

setting.
Alias
SPI_SetKbdDelay(), SetKbdDelay(), SetKeyboardSelay()
Syntax
SPI_SetKeyboardDelay( nValue )  lSuccess

SPI Functions
Parameters
nValue repeat-delay setting.
Returns
See also
SPI_SetKeyboardSpeed(), KEY_fast(), KEY_slow(), KEY_norm()
SPI_SetKeyboardSpeed() : Sets the keyboard repeat-speed

setting.
Alias
SPI_SetKbdSpeed(), SetKbdSpeed(), SetKeyboardSpeed()
Syntax
SPI_SetKeyboardSpeed( nValue )  lSuccess
Parameters
nValue repeat-speed setting.
Returns
See also
SPI_SetKeyboardDelay(), KEY_fast(), KEY_slow(), KEY_norm()
SPI_SetMenuDropAlignment() : Sets the alignment value of

pop-up menus.
Syntax
SPI_SetMenuDropAlignment( lAlignment )  lSuccess
Parameters
lAlignment .T. for left-aligned; .F. otherwise.
Returns
SPI_SetMouseButtonSwap() : Swaps or restores the meaning

of the left and right mouse buttons.
Syntax
SPI_SetMouseButtonSwap( lSwap )  lSuccess

SPI Functions
Parameters
lSwap .T. to swap the meanings of the buttons; .F. to restore it.
Returns
SPI_SetScreenSaveActive() : Sets the state of the screen

saver.
Syntax
SPI_SetScreenSaveActive( lSetting )  lSuccess
Parameters
lSetting .T. to set the screen saver state, .F. otherwise.
Returns
SPI_SetScreenSaveTimeout() : Sets the screen saver time-out

value.
Syntax
SPI_SetScreenSaveTimeout( nValue )  lSuccess
Parameters
nValue screen saver time-out value.
Returns
SPI_SetWallpaper() : Sets the Windows wallpaper.

Comment
If you also want to set the tiled property, you must set the TileWallpaper entry in the WIN.INI file manually.
Syntax
SPI_SetWallpaper( szFile )  lSuccess
Parameters
szFile string containing the name of a bitmap file.
Returns

SPI Functions
Example
LOCAL szFile
m.szFile = FIL_get( "BMP files " + CHR(0) + "*.BMP" + ;

CHR(0) + CHR(0) , ;
"Changing the Windows wallpaper" , ;
"." , ;
0 )
IF ( ! EMPTY( m.szFile ) )
&& For a tiled wallpaper
FIL_wwriin( "Desktop","TileWallpaper","1" )
SPI_SetWallpaper( m.szFile )
ENDIF
SPI_SetWorkArea() : Retrieves the size of the working area.

Syntax
SPI_SetWorkArea( nTop,nLeft,nBottom,nRight )  lSuccess
Parameters
nTop top of rectangle.
nLeft left of rectangle.
nBottom bottom of rectangle.
nRight right of rectangle.
Returns
SPI_Successful() : Returns the string that is used to declare

Syntax
SPI_Successful()  szConstant
Parameters
None.
Returns
szConstant "The operation completed successfully".

String Functions
String Functions

String Functions
STR_addcod() : Adds an ASCII code to each character of a

string.
Syntax
STR_addcod( szString,nCode )  szResult
Parameters
szString string to process.
nCode ASCII code to add to each character.
Returns
szResult resulting string.
Example
? STR_addcod( "12345678",1 ) && "23456789"
STR_AllChars() : Returns all the characters found in a string in

a sorted manner.
Remark
This algorithm is used in SCRABBLE for example … to locate ANY word that contains all letters, or 7 letters, or 6 letters,
etc.. Very efficient.
Syntax
STR_AllChars( szString[,nType] )  szResult
Parameters
nType Type of treatment: 0 … case-sensitive; 1 … uses uppercase algorithm; 2 … uses lowercase

algorithm. This parameter is optional. By default, 0 is used.
Returns
Example
LOCAL szString
m.szString = "Hello World"
? STR_AllChars( m.szString ) && "HWdelor"

? STR_AllChars ( m.szString,0 ) && "HWdelor"
? STR_AllChars ( m.szString,1 ) && "DEHLORW"
? STR_AllChars ( m.szString,2 ) && "dehlorw"
STR_ascii() : Forms a number based on each character value.

Syntax
STR_ascii( szString )  nResult

String Functions
Parameters
Returns
nResult resulting number.
Example
? STR_ascii ( "AA" ) && 130
? STR_ascii2( "AA" ) && 195
? STR_ascii ( "AB" ) && 131
? STR_ascii2( "AB" ) && 197
STR_ascii2() : Forms a number based on each character value

multiplied by its position.
Syntax
STR_ascii2( szString )  nResult
Parameters
Returns
nResult resulting number.
Example
? STR_ascii ( "AA" ) && 130
? STR_ascii2( "AA" ) && 195
? STR_ascii ( "AB" ) && 131
? STR_ascii2( "AB" ) && 197
STR_Ascii2Ebcdic() : Converts a string to its EBCDIC

equivalent.
Syntax
STR_Ascii2Ebcdic( szAscii )  szEbcdic
Parameters
szAscii string to process.
Returns
szEbcdic resulting number.
Example
LOCAL szString
m.szString = STR_Ascii2Ebcdic( "Hello World" )

? m.szString && "È…““–@æ–™“„"
? STR_ Ebcdic2Ascii( m.szString ) && "Hello World"

String Functions
STR_AtLine() : Determines the number of the line a given
position belongs to.
Syntax
STR_AtLine( n,szString )  nLine
Parameters
n the position.
Returns
nLine line number. Please note that unlike VFP native ATLINE() function, the STR_AtLine()
function does not rely on SET MEMOWIDTH to calculate the line number: only the sequence
CR + LF ( CHR(13) + CHR(10) ) controls the line jump.
Example
&& This example searches an entire source code (.PRG) and locates
&& Change Control Tags so that they can be documented automatically
&& A Change Control tag has the following form:
&&
&& <cc date="20010520120000" auth="Anurak">
&& ... the code that is enclosed within the tags
&& </cc date="20010520120000">
&& As you can see there is an opening tag, and a closing tag
&&
LOCAL szCode
LOCAL nStart
LOCAL nEnd
LOCAL nEnd2
LOCAL nMatch
LOCAL szToken
LOCAL i
LOCAL szDateTime
LOCAL szAuthor
LOCAL szRef
LOCAL szComment
LOCAL nAtLine && Starting line
LOCAL nAtLine2 && Ending line
&& m.szFile is the .PRG file to read

m.szCode = FILETOSTR( m.szFile )
&& We won't use this variable but we need it for STR_like()

m.nMatch = 0
&& Staring position to start searching (STR_like())
m.nStart = 1
&& Without regard to case
STR_LikeCase( .F. )
WAIT WINDOW "Parsing the code. Please wait..." NOWAIT
IF ( ! EMPTY( m.szCode ) )
m.n
&& Process the entire string
DO WHILE ( .T. )
&& If we can find the opening tag … where does it end?

m.nEnd = STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,3,@nMatch,m.nStart )
&& Did we find the opening tag?

IF ( m.nEnd != 0 )
&& We found it … and because we asked FOCUS to store the 3rd placeholder
&& we now can simply extract the Date/Time value
m.szDateTime = STR_LikeGetToken()

String Functions
&& That's the line number where we found the opening tag
m.nAtLine = STR_AtLine( m.nEnd,m.szCode )
&& Let's get the author name now

IF ( STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 )
m.szAuthor = STR_LikeGetToken()
ELSE
m.szAuthor = ""
ENDIF
&& Let's get an optional reference number (in case the Change Control
&& has been assigned such a number)
IF ( STR_Like( [*<cc*date="*"*ref="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 )
m.szRef = STR_LikeGetToken()
ELSE
m.szRef = ""
ENDIF
&& If we want to be exhaustive, we might as well

&& extract an optional comment (sounds a good idea)
IF ( STR_Like([*<cc*date="*"*comment="*"*>*],m.szCode,5,@nMatch,m.nStart) != 0 )
m.szComment = STR_LikeGetToken()
ELSE
m.szComment = ""
ENDIF
&& Let's remember where the oepning tag was ending … because,
&& this will be used to continue the scanning of the source code
m.nStart = m.nEnd
&& Searching for the closing tag now

m.nEnd2 = STR_Like( [*</cc*date="] + m.szDateTime + ;
[*>*],m.szCode,3,@nMatch,m.nEnd )
&& If we found it
IF ( m.nEnd2 != 0 )
&& To which line of the source code this tag belongs to?
m.nAtLine2 = STR_AtLine( m.nEnd2,m.szCode )
ELSE
m.nAtLine2 = -1
ENDIF
&& Imagine we put what we found in a list control

&& OK, ok … we don't use the reference number nor do
&& we use the comment! But this is merely an example, right?
.lstCCtrl.AddItem( "CC Author: " + m.szAuthor + " -- " + ;
"Date : " + m.szDateTime + " -- " + ;
"Start:" + ALLTRIM( STR( m.nAtLine ) ) + " ... " + ;
"End:" + ALLTRIM( STR( m.nAtLine2 ) ) ;
)
ELSE
&& No opening tag found => we can exit the routine
EXIT
ENDIF
ENDDO
ENDIF
WAIT WINDOW "Done!" NOWAIT
STR_balanc() : Finds position where a given character is

balanced with another.
Syntax
STR_balanc( szString,szDelimiters,nOccurrence )  nPosition
Parameters

String Functions
szDelimiters two characters string.
nOccurrence occurrence to check for.
Returns
nPosition position where character is balanced. szString starts at 1. If not found, 0.
Example
LOCAL szVar
szVar = "MyFunc( People( 1,23,78 ))"

? STR_balanc( szVar,"()",2 ) && 26 = position where closing
&& parenthesis is found
STR_char() : Extracts the rest of a string.

Alias
STR_rest() .
Caution
No test is made on the parameters. Passing wrong parameters can produce unexpected results.
Syntax
STR_char( szString,nPosition )  szResult
Parameters
nPosition position at which extraction starts.
Returns
Example
? STR_char( "Hello World",3 ) && "llo World"
STR_chrcnt() : Counts occurrences of a character in a string.

Syntax
STR_chrcnt( szString,cChar )  nOccurrences
Parameters
cChar character to search for.
Returns
nOccurrences number of occurrences of cChar in szString .

String Functions
Example
? STR_chrcnt( "Hello World","l" ) // 3
STR_chrswa() : Swaps one character with another within a

string.
Syntax
STR_chrswa( szString,cToBeReplaced,cReplacement )  szNewString
Parameters
szString string to be processed.
cToBeReplaced character that should be replaced with cReplacement .
cReplacement character to substitute to cToBeReplaced .
Returns
szNewString resulting string.
Example
? STR_chrswa( "Hello World","l","A" ) && "HeAAo WorAd"
STR_comma() : Formats a string that only contains digits.

Syntax
STR_comma( szString,cComma )  szNumber
Parameters
cComma character that represents a comma.
Returns
szNumber resulting string.
Example
? STR_comma( "1024.78","," ) && "1.024,78"
? STR_comma( "1024.78","." ) && "1,024.78"
STR_CompareStrings() : Compares two character strings,

using the current User Locale as the basis for the
comparison.
Syntax
STR_CompareStrings( szString1,szString2,nFlags )  nResult
Parameters
szString1 first string to compare.

String Functions
szString2 second string to compare.
nFlags comparison flags. These flags indicate how the function compares the two strings. By default,
these flags are not set. This parameter can specify zero to get the default behavior, or it can be
any combination of the following values :
Manifest Constant Value Meaning

NORM_IGNORECASE 0x00000001 Ignore case.
NORM_IGNOREKANATYPE 0x00010000 Do not differentiate between Hiragana and
Katakana characters. Corresponding
Hiragana and Katakana characters compare
as equal.
NORM_IGNORENONSPACE 0x00000002 Ignore non-spacing characters.
NORM_IGNORESYMBOLS 0x00000004 Ignore symbols.
NORM_IGNOREWIDTH 0x00020000 Do not differentiate between a single-byte
character and the same character as a
double-byte character.
SORT_STRINGSORT 0x00001000 Treat punctuation the same as symbols.
Returns
nResult If the function succeeds, the return value is one of the following values :
Value Meaning
1 szString1 parameter is less in lexical value than the string pointed to by the
szString2 parameter.
2 szString1 is equal in lexical value to szString2 .
3 szString1 is greater in lexical value than szString2 .
If the function fails, the return value is zero.
STR_Compare() : Compares two character strings, and reports

where they differ.
Syntax
STR_Compare( szString1,szString2[,nFlags] )  nOffset
Parameters
szString1 first string to compare.
szString2 second string to compare.
nFlags comparison flags (optional). When not passed, the two strings are strictly compared. The only
supported flag is:

NORM_IGNOREWIDTH 0x00020000 Do not differentiate between a single-byte
character and the same character as a double-
byte character.

String Functions
Returns
nResult 0 indicates that both strings are identical; otherwise, the return value is the offset where the
strings differ.
STR_ConvertA2B() : Converts a character string based on an

internal conversion table.
Remark
STR_SetConvTable() can be used to set the internal conversion table used by the STR_ConvertA2B() and
STR_ConvertB2A() functions.
All together, these functions permit to convert character strings: a 'A' must be transformed into a 'C' , a 'C' into a
'B' , a 'B' into a 'A' , … It can be used to scramble strings. Likewise, it can be used to issue ASCII to EBCDIC
transformations.
Syntax
STR_ConvertA2B( szStr )  szResult
Parameters
szStr the string to treat.
Returns
szResult szStr transformed thanks to the internal conversion table. The internal conversion table can
be altered thanks to STR_SetConvTable() and STR_SetCharConversion() .
Example
LOCAL iCharH,iCharW
LOCAL szString
m.iCharH = ASC( 'H' )

m.iCharW = ASC( 'W' )
&& Every 'H' should be turned into a 'W'

STR_SetCharConversion( m.iCharH,m.iCharW )
&& Every 'W' should be turned into a 'H'

STR_SetCharConversion( m.iCharW,m.iCharH )
m.szTransformed = STR_ConvertA2B( m.szString ) && "Wello Horld"

? STR_ConvertB2A( szTransformed ) && "Hello World"
See also
STR_ConvertB2A() , STR_SetCharConversion() , STR_SetConvTable() .
STR_ConvertB2A() : Reverses the conversion set by the

STR_ConvertA2B() function.
Remark
STR_SetConvTable() can be used to set the internal conversion table used by the STR_ConvertA2B() and
STR_ConvertB2A() functions.

String Functions
transformations.
Syntax
STR_ConvertB2A( szStr )  szResult
Parameters
szStr the string to treat.
Returns
szResult szStr transformed thanks to the internal conversion table. The internal conversion table can
be altered thanks to STR_SetConvTable() and STR_SetCharConversion() .
Example
LOCAL iCharH,iCharW
LOCAL szString




See also
STR_ConvertA2B() , STR_SetCharConversion() , STR_SetConvTable() .
STR_cpbrk() : Finds the 1st occurrence in a string of any

character from another string. String result.
Syntax
STR_cpbrk( szString1,szString2 )  szString
Parameters
szString1 string to be search for.
szString2 string to look for characters.
Returns
szString resulting character string.
Example
? STR_cpbrk( "The 3 men and 2 dogs ate 5 pigs","0123456789" )
&& "3 men and 2 dogs ate 5 pigs"

String Functions
STR_Decode64() : Decodes a base 64 encoded string.
Syntax
STR_Decode64( szBase64 )  szString
Parameters
szBase64 the character string that is base 64 encoded.
Returns
szString original string.
Example
LOCAL szString
LOCAL szEncrypted
LOCAL szDecrypted
m.szEncrypted = STR_Encode64( m.szString ) && "SGVsbG8gV29ybGQ="

m.szDecrypted = STR_Decode64( m.szEncrypted ) && "Hello World"
IF ( m.szDecrypted == m.szString )
? "It worked"
ELSE
? "It didn't worked"
ENDIF
STR_dionly() : Keeps digits only.

Syntax
STR_dionly( szString )  szResult
Parameters
Returns
szResult resulting string. Only digits and decimal separator are kept ( ".").
Example
? STR_dionly( "Hello the 101 dogs" ) && "101"
STR_Ebcdic2Ascii() : Converts a string to its ASCII equivalent.

Syntax
STR_Ebcdic2 Ascii(szEbcdic )  szAscii
Parameters
szEbcdic string to process.
Returns
szAscii resulting number.

String Functions
Example
LOCAL szString
m.szString = STR_Ascii2Ebcdic( "Hello World" )

? m.szString && "È…““–@æ–™“„"
? STR_ Ebcdic2Ascii( m.szString ) && "Hello World"
STR_Encode64() : Encodes a string in base 64.

Syntax
STR_Encode64( szString )  szBase64
Parameters
Returns
szBase64 the character string base 64 encoded.
Example
LOCAL szString
LOCAL szEncrypted
LOCAL szDecrypted
m.szEncrypted = STR_Encode64( m.szString ) && "SGVsbG8gV29ybGQ="

m.szDecrypted = STR_Decode64( m.szEncrypted ) && "Hello World"
IF ( m.szDecrypted == m.szString )
? "It worked"
ELSE
? "It didn't worked"
ENDIF
STR_encrypt() : Encrypts a string.

Remark
The function can be applied on its own return to retrieve the original string.
Syntax
STR_encrypt( szString,szCode )  szResult
Parameters
szCode code for encryption.
Returns
szResult the encrypted string.
Example
LOCAL szEncrypted
LOCAL szCode
szCode = "This is a regular string"

szEncrypted = STR_encrypt( "Hello World",szCode )
IF ( STR_encrypt( szEncrypted,szCode ) != "Hello World" )

String Functions
? "The string cannot be decrypted! Strange!"
ENDIF
STR_end() : Does a string end with a given value?

Syntax
STR_end( szString1,szString2 )  lResult
Parameters
szString1 string to process.
szString2 string to look for.
Returns
lResult .T. if szString1 ends with szString2 .
Example
? STR_end( "Hello World","rld" ) && .T.
See also
STR_start()
STR_exclude() : Excludes characters that are in a string.

Alias
Exclude() , STR_exclud() , ExcludeChars() , ExcludeChar() , STR_Discard() , STR_eliminate() .
Syntax
STR_exclude( szString,szToExclude )  szResult
Parameters
szToExclude string from which each character should be excluded from szString .
Returns
Example
LOCAL szString
&& This eliminates the Carriage return/line feeds of a text file

m.szString = STR_exclude( FILETOSTR( "D:\MYFILE.TXT" ),CHR(13)+CHR(10) )
? STR_exclude( "Hello World","Hlo") && "e Wrd"

String Functions
STR_find() : Finds an occurrence of a substring in a string
(two times faster than AT()).
Remark
The function uses the BOYER-MOORE algorithm for fast string searches. the pattern to look for cannot contain
embedded NULs (CHR(0) ) and it should be larger than 4 characters to notice performance gains.
Syntax
STR_find( szPattern,szString )  nPos
Parameters
szPattern the substring to look for in szString . szPattern cannot contain embedded NULs (CHR(0) ).
If szPattern is smaller than 5 characters, the internal search won't be optimized and you
won't notice performance gains compared to AT() .
szString string to search.
Returns
nPos position where szPattern was found in szString .
Example
LOCAL szString,szPattern,nLoops,dNow,i
CLEAR
m.szPattern = "Hello guys!"

m.szString = REPLICATE( "The sun shines. I think that tomorrow" + ;
" it will shine too. ",500 ) + m.szPattern
m.nLoops = 1000
m.dNow = GetTickCount()
FOR m.i = 1 TO m.nLoops

AT( m.szPattern,m.szString )
NEXT
? GetTickCount() - m.dNow,"milliseconds for AT() function"
m.dNow = GetTickCount()
FOR m.i = 1 TO m.nLoops

STR_Find( m.szPattern,m.szString )
NEXT
? GetTickCount() - m.dNow,"milliseconds for STR_find() function"
See also
STR_FindBackward()
STR_FindBackward() : Finds an occurrence of a substring in a

string (two times faster than RAT()) starting from the end
of the string.
Remark
The function uses the BOYER-MOORE algorithm for fast string searches. the pattern to look for cannot contain
embedded NULs (CHR(0) ) and it should be larger than 4 characters to notice performance gains.

String Functions
Syntax
STR_findBackward( szPattern,szString )  nPos
Parameters
szPattern the substring to look for in szString . szPattern cannot contain embedded NULs (CHR(0) ).
If szPattern is smaller than 5 characters, the internal search won't be optimized and you
won't notice performance gains compared to AT() .
szString string to search.
Returns
nPos position where szPattern was found in szString .
See also
STR_Find()
STR_first() : Finds the first character that is not a space.

Syntax
STR_first( szString )  cChar
Parameters
szString string to find the first character from.
Returns
cChar first character that is not a space in szString . The string is processed from right to left.
Example
? STR_first( "Hello World" ) && "H"
? STR_first( " Hello" ) && "H"
See also
STR_last()
STR_FormatByteSize() : Converts a numeric value into a string

that represents the number expressed as a size value in
bytes, kilobytes, megabytes, or gigabytes, depending on
the size.
Syntax
STR_FormatByteSize( n )  szSize
Parameters
n integer to treat as a size in bytes.
Returns
szSize resulting number.

String Functions
Example
? STR_FormatByteSize(100) && "100 bytes"
? STR_FormatByteSize(1000) && "1000 bytes"
? STR_FormatByteSize(2000) && "1,95 KB"
? STR_FormatByteSize(1024*1024*1024) && "1,00 GB"
STR_getoff() : Gets the internal offset position.

Comment
STR_getoff() is one of the token functions. This function is intended to be used when accessing one token after
another. In this sense, tokens are not reached at random. STR_getoff() interrogates the internal counter Offset.
Syntax
STR_getoff()  nOffset
Parameters
None.
Returns
nOffset value returned by this function indicates the offset position prior STR_toknex() did reach
when retrieving tokens from a string.
See Also
STR_tokini() , STR_toknex() , STR_tokfin() .
STR_GeneratePassword() : Generates a random password.

Syntax
STR_GeneratePassword( [nLength[,nStrategy]] )  szPwd
Parameters
nLength optional length of the generated password. By default szPwd is 8 characters long.
nStrategy optional strategy when generating the password. By default, each character of szPwd is
generated using a random strategy.
Strategy Description
0 szPwd will contain digits only.
1 szPwd will contain uppercase letters only.
2 szPwd will contain lowercase letters only.
Returns
szPwd the generated password.
Example
? STR_GeneratePassword() && "M5RPY453"
? STR_GeneratePassword( 10 ) && "31B12cT9LE"
? STR_GeneratePassword( 10,0 ) && "5709359440"
? STR_GeneratePassword( 10,1 ) && "QVAADIVKFL"
? STR_GeneratePassword( 10,2 ) && "gpjjpfdojr"

String Functions
STR_hexa() : Hexadecimal equivalent of a string.
Caution
The STR_hexa() function does not evaluate correctly when accented characters must be converted.
Alias
stoh()
Syntax
STR_hexa( szString )  szHex
Parameters
Returns
szHex hexadecimal equivalent of szString .
Example
? STR_hexa( "DVL Group" ) && "44564C2047726F7570"
? STR_htos("44564C2047726F7570" ) && "DVL Group"
See also
NUM_hexa() , STR_htos() , NUM_htoi()
STR_htos() : Original string corresponding to an hexadecimal

string.
Caution
The STR_htos() function does not evaluate correctly when it must restore accented characters must be converted.
Alias
htos()
Syntax
STR_htos( cHexaString )  szString
Parameters
cHexaString string to process.
Returns
szString original string.
Example
? STR_hexa( "DVL Group" ) && "44564C2047726F7570"
? STR_htos("44564C2047726F7570" ) && "DVL Group"
See also
STR_hexa()
String Functions
STR_IsAlpha() : Determines if a given string contains only
alpha characters.
Remark
Unlike the ISALPHA() function of Visual FoxPro which only considers the first character, this makes it possible to
examine the entire string, or only a portion of it.
Syntax
STR_IsAlpha( szString[,nStart[,nCount]] )  lResult
Parameters
nStart specifies the position in the character string to examine. This parameter is optional. Default is 0.
nCount specifies the number of characters to test. This parameter is optional. Default is equal to the
length of the string from the nStart position.
Returns
lResult .T. if the string is only made of alpha characters. .F. otherwise.
Example
? STR_IsAlpha( "Hello All Of You" ) && .F.
? STR_IsAlpha( "Hello All Of You",1,5 ) && .T.
? STR_IsAlpha( "Hello All Of You",1,6 ) && .F.
See also
STR_IsUpper() , STR_IsLower() , STR_IsAlphaNumeric() , STR_IsPunct() , STR_IsSpace() ,
STR_IsPrint() , STR_IsGraph() , STR_IsVowel() , STR_IsConsonant()
STR_IsAlphaNumeric() : Determines if a given string contains

only alphanumeric characters.
Syntax
STR_IsAlphaNumeric( szString[,nStart[,nCount]] )  lResult
Parameters
Returns
lResult .T. if the string is only made of alphanumeric characters. .F. otherwise.
Example
? STR_IsAlphaNumeric( "MYFILE105.EXT" ) && .F.
? STR_IsAlphaNumeric( "MYFILE105.EXT",1,9 ) && .T.

String Functions
? STR_IsAlphaNumeric( "MYFILE105.EXT",1,10 ) && .F.
See also
STR_IsUpper() , STR_IsLower() , STR_IsAlpha() , STR_IsPunct() , STR_IsSpace() , STR_IsPrint() ,
STR_IsGraph() , STR_IsVowel() , STR_IsConsonant()
STR_IsPunct() : Determines if a given string contains only

punctuation marks.
Syntax
STR_IsPunct( szString[,nStart[,nCount]] )  lResult
Parameters
Returns
lResult .T. if the string is only made of punctuation marks. .F. otherwise.
Example
? STR_IsPunct( "MYFILE105.EXT" ) && .F.
? STR_IsPunct( "MYFILE105.EXT",10 ) && .F.
? STR_IsPunct( "MYFILE105.EXT",10,1 ) && .T.
See also
STR_IsUpper() , STR_IsLower() , STR_IsAlpha() , STR_IsAlphaNumeric() , STR_IsSpace() ,
STR_IsSpace() : Determines if a given string contains only

spaces.
Syntax
STR_IsSpace( szString[,nStart[,nCount]] )  lResult
Parameters
Returns
lResult .T. if the string is only made of spaces. .F. otherwise. The following characters are considered
to be spaces : CHR(9) , CHR(10) , CHR(11) , CHR(12) , CHR(13) , CHR(32) .

String Functions
See also
STR_IsUpper() , STR_IsLower() , STR_IsAlpha() , STR_IsAlphaNumeric() , STR_IsPunct() ,
STR_IsGraph() : Determines if a given string contains only

graph characters.
Syntax
STR_IsGraph( szString[,nStart[,nCount]] )  lResult
Parameters
Returns
lResult .T. if the string is only made of spaces. .F. otherwise. Only the representation of any ASCII
or Katakana printable character except a white space are considered to be graph characters : !,
", #, $, %, &, ', (, ), *, +, ,, -, ., /, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, :, ;, <, =, >,?, @, A, B, C, D, E,
F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, [, \, ], ^, _, `, a, b, c, d, e, f, g, h, i,
j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, {, |, }, ~.
See also
STR_IsPrint() , STR_IsSpace() , STR_IsVowel() , STR_IsConsonant()
STR_IsPrint() : Determines if a given string contains only

graph characters.
Syntax
STR_IsPrint( szString[,nStart[,nCount]] )  lResult
Parameters
Returns
lResult .T. if and only if the string is only made of single-byte representations of any ASCII or
Katakana printable character including a white space.

String Functions
See also
STR_IsGraph() , STR_IsSpace() , STR_IsVowel() , STR_IsConsonant()
STR_IsCharAlpha() : Determines if a given character is an

alpha character.
Remark
Unlike the ISALPHA() function of Visual FoxPro which only considers the first character, this makes it possible to
examine a particular character of the string.
Syntax
STR_IsCharAlpha( szString[,nPosition] )  lResult
Parameters
nPosition specifies the position in the character string to examine. Optional parameter.
Returns
lResult .T. if the character is an alpha character. .F. otherwise.
Example
? STR_IsCharAlpha( "Hello",1 ) && .T.
See also
STR_IsUpper() , STR_IsLower() , STR_IsCharLower() , STR_IsCharUpper() ,
STR_IsCharAlphaNumeric() , STR_IsCharPunct() , STR_IsCharSpace() , STR_IsCharPrint() ,
STR_IsCharGraph() .
STR_IsCharAlphaNumeric() : Determines if a given character is

an alphanumeric character.
Remark
Unlike the ISALPHA() function of Visual FoxPro which only considers the first character and alpha characters, this
makes it possible to examine a particular character of the string plus numerics.
Syntax
STR_IsCharAlphaNumeric( szString[,nPosition] )  lResult
Parameters
Returns
lResult .T. if the character is an alphanumeric character. .F. otherwise.

String Functions
Example
? STR_IsCharAlphaNumeric( "101 dogs",1 ) && .T.
See also
STR_IsUpper() , STR_IsLower() , STR_IsCharLower() , STR_IsCharUpper() , STR_IsCharAlpha ,
STR_IsCharPunct() , STR_IsCharSpace() , STR_IsCharPrint() , STR_IsCharGraph() .
STR_IsCharDigit() : Is a given character a digit?

Syntax
STR_IsCharDigit( szString[,nPosition] )  lResult
Parameters
Returns
lResult STR_IsCharDigit() returns a .T. value if the character is a digit. Otherwise it returns .F. .
See also
STR_IsUpper() , STR_IsLower() , STR_IsCharUpper() , STR_IsCharLower() , STR_IsCharAlpha() ,
STR_IsCharAlphaNumeric() , STR_IsCharPunct() , STR_IsCharPrint() , STR_IsCharSpace() .
STR_IsCharGraph() : Is a given character printable while not

being a space?
Syntax
STR_IsCharGraph( szString[,nPosition] )  lResult
Parameters
Returns
lResult STR_IsCharGraph() returns a .T. value if the character is a printable character other than a
space. Otherwise it returns .F. .
See also
STR_IsCharAlphaNumeric() , STR_IsCharPunct() , STR_IsCharPrint() , STR_IsCharSpace() .

String Functions
STR_IsCharLower() : Determines if a given character of a
specified string is a lowercase character.
Remark
Unlike the ISLOWER() function of Visual FoxPro which only considers the first character, this makes it possible to
Syntax
STR_IsCharLower( szString[,nPosition] )  lResult
Parameters
Returns
lResult is the character in a lowercase format? .T. if yes, .F. if not.
Example
? STR_IsCharLower( "Hello",1 ) && .F.
? STR_IsCharLower( "Hello",2 ) && .T.
See also
STR_IsUpper() , STR_IsLower() , STR_IsCharUpper() , STR_IsCharAlpha() ,
STR_IsCharGraph() .
STR_IsCharPrint() : Is a given character printable?

Syntax
STR_IsCharPrint( szString[,nPosition] )  lResult
Parameters
Returns
lResult STR_IsCharPrint() returns a .T. value if the character is a printable character, including
the space character. Otherwise it returns .F..
See also
STR_IsCharAlphaNumeric() , STR_IsCharPunct() , STR_IsCharGraph() , STR_IsCharSpace() .

String Functions
STR_IsCharPunct() : Is a given character a punctuation
character?
Syntax
STR_IsCharPunct( szString[,nPosition] )  lResult
Parameters
Returns
lResult is the character a punctuation character? STR_IsCharPunct() returns .T. for any printable
character that is not a space character. Otherwise it returns .F..
Example
? STR_IsCharPunct( "Hello World.",12 ) && .T.
See also
STR_IsCharAlphaNumeric() , STR_IsCharSpace() , STR_IsCharPrint() , STR_IsCharGraph() .
STR_IsCharSpace() : Is a given character a white space

character?
Syntax
STR_IsCharSpace( szString[,nPosition] )  lResult
Parameters
Returns
lResult is the character a white space character? STR_IsCharSpace() returns a .T. value if the
character is a white-space character (CHR(9) , CHR(10) , CHR(13) , CHR(32) ). Otherwise it
returns .F..
Example
? STR_IsCharSpace( "Hello World",6 ) && .T.
See also
STR_IsCharAlphaNumeric() , STR_IsCharPunct() , STR_IsCharPrint() , STR_IsCharGraph() .

String Functions
STR_IsCharUpper() : Determines if a given character of a
specified string is an uppercase character.
Remark
Unlike the ISUPPER() function of Visual FoxPro which only considers the first character, this makes it possible to
Syntax
STR_IsCharUpper( szString[,nPosition] )  lResult
Parameters
Returns
lResult is the character in an uppercase format? .T. if yes, .F. if not.
Example
? STR_IsCharUpper( "Hello",1 ) && .T.
? STR_IsCharUpper( "Hello",2 ) && .F.
See also
STR_IsUpper() , STR_IsLower() , STR_IsCharLower() , STR_IsCharAlpha() ,
STR_IsCharGraph() .
STR_IsCharXDigit() : Determines if a given character of the

specified string is a hexadecimal digit.
Syntax
STR_IsCharXDigit( szString[,nPosition] )  lResult
Parameters
nPosition specifies the position in the character string to examine. If not passed, the first character of the
string is examined.
Returns
lResult .T. if the character is a hexadecimal digit; .F. if not.
Example
? STR_IsCharXDigit( "0123456789ABCDEF" ) && .T.
? STR_IsCharXDigit( "0123456789ABCDEFG",17 ) && .F.

String Functions
See also
STR_IsUpper() , STR_IsCharLower() , STR_IsCharUpper() , STR_IsCharAlpha() ,
STR_IsCharDigit() , STR_IsCharGraph() , STR_IsXDigit() .
STR_IsDigit() : Determines if characters of the specified string

are digits.
Remark
Unlike the ISDIGIT() function of Visual FoxPro which only considers the first character, this makes it possible to
examine a part of a string or the whole string. The developer can mention a position from where he wants to process
the string, and additionally he can mention a number of characters to process.
Syntax
STR_IsDigit( szString[,nStart[,nLength]] )  lResult
Parameters
nStart specifies the position in the character string from where the string is going to be processed.
Optional. When not mentioned, the string is processed from the first position.
nLength specifies the number of characters to process. Optional. When not mentioned, the string is
processed from the starting position to the end of the string.
Returns
lResult are all the examined characters digits? .T. if yes, .F. if not.
Example
? STR_IsDigit( "Hello101" ) && .F.
? STR_IsDigit( "Hello101" ,6 ) && .T.
? STR_IsDigit( "Hello101a",6 ) && .F.
? STR_IsDigit( "Hello101a",6,3 ) && .T.
See also
STR_IsCharDigit() , STR_IsCharGraph() .
STR_IsDigitOrDecimalSeparator() : Determines if characters of

the specified string are digits or decimal separator (".").
Syntax
STR_IsDigitOrDecimalSeparator( szString[,nStart[,nLength]] )  lResult
Parameters
nStart specifies the position in the character string from where the string must be processed. Optional.
If not mentioned, the string is processed from the first position ( 1).

String Functions
nLength specifies the number of characters to process. Optional. If not mentioned, the string is
Returns
lResult are all characters digits and/or decimal separators ('.' )? .T. if yes, .F. if not.
Example
? STR_IsDigit( "101.8" ) && .F.
? STR_IsDigitOrDecimalSeparator( "101.8" ) && .T.
See also
STR_IsCharDigit() , STR_IsCharGraph() .
STR_IsInSet() : Determines if characters of the specified string

belongs to a set of characters.
Alias
IsInSet(), InSet()
Syntax
STR_IsInSet( szString,szCharacters[,nStart[,nLength]] )  lResult
Parameters
szCharacters characters that must be taken in account.
Returns
lResult are all the examined characters belonging to the cCharacters set of characters? .T. if yes,
.F. if not.
Example
? STR_IsInSet( " –123.18"," +-0123456789." ) && .T.
See also
STR_IsCharGraph() .
STR_IsNumber() : Determines if a string forms a number.

Syntax
STR_IsNumber( szString )  lIsNumber

String Functions
Parameters
Returns
lIsNumber .T. if szString can be evaluated to a number; .F. if not.
Example
? STR_IsNumber( "45" ) && .T.
? STR_IsNumber( "45a" ) && .F.
? STR_IsNumber( "45+12" ) && .T.
? STR_IsNumber( "45-12" ) && .T.
STR_IsLower() : Determines if characters of the specified

string are lowercase characters.
Remark
Unlike the ISLOWER() function of Visual FoxPro which only considers the first character, this makes it possible to
examine a part of a string. The developer can mention a position from where he wants to process the string, and
additionally he can mention a number of characters to process.
Syntax
STR_IsLower( szString[,nStart[,nLength]] )  lResult
Parameters
Returns
lResult are all the examined characters in a lowercase format? .T. if yes, .F. if not.
Example
? STR_IsLower( "Hello" ) && .F.
? STR_IsLower( "Hello",2 ) && .T.
? STR_IsLower( "HelLo",2,2 ) && .T.
See also
STR_IsCharGraph() .

String Functions
STR_IsUpper() : Determines if characters of the specified
string are uppercase characters.
Remark
Unlike the ISUPPER() function of Visual FoxPro which only considers the first character, this makes it possible to
examine a part of a string. The developer can mention a position from where he wants to process the string, and
additionally he can mention a number of characters to process.
Syntax
STR_IsUpper( szString[,nStart[,nLength]] )  lResult
Parameters
Returns
lResult are all the examined characters in an uppercase format? .T. if yes, .F. if not.
Example
? STR_IsUpper( "hELLO" ) && .F.
? STR_IsUpper( "hELLO",2 ) && .T.
? STR_IsUpper( "hELlo",2,2 ) && .T.
? STR_IsUpper( "hELlo",2,3 ) && .F.
See also
STR_IsLower() , STR_IsCharLower() , STR_IsCharUpper() , STR_IsCharAlpha() ,
STR_IsCharGraph() .
STR_IsValidCreditCard() : Determines whether a credit card

number is correct or not.
Syntax
STR_IsValidCreditCard( cNumber )  lCorrect
Parameters
cNumber credit card number with a maximum of 16 digits (if more, the function may generate illegal
operations). Non digit characters are disregarded.
Returns
lCorrect .T. if the credit card number is valid; .F. if not.
Example
? STR_IsValidCreditCard( "6045.4360.3078.4771" ) && .F.

String Functions
STR_IsXDigit() : Determines if characters of the specified
string are hexadecimal digits.
Syntax
STR_IsXDigit( szString[,nStart[,nLength]] )  lResult
Parameters
Returns
lResult are all the examined characters hexadecimal digits? .T. if yes, .F. if not.
Example
? STR_IsXDigit( "0123456789aBCDEF" ) && .T.
? STR_IsXDigit( "0123456789ABCDEF" ) && .T.
? STR_IsXDigit( "0123456789ABCDEFG" ) && .F.
? STR_IsXDigit( "0123456789ABCDEFG",1,16 ) && .T.
See also
STR_IsLower() , STR_IsCharLower() , STR_IsCharUpper() , STR_IsCharAlpha() ,
STR_IsCharGraph() , STR_IsCharXDigit() .
STR_keep() : Keeps specified characters from a string.

Syntax
STR_keep( szString,szCharacters )  szNewString
Parameters
szCharacters characters to keep in string.
Returns
szNewString resulting string. The function is case sensitive !
Example
? STR_keep( "Hello World","lod" ) && "lloold" (Length = 6)
STR_KeepConsonants() : Keeps the consonants of a string.

Syntax
STR_KeepConsonants( szString )  szNewString

String Functions
Parameters
Returns
Example
? STR_KeepConsonants( "Hello World" ) && "HllWrld"
STR_KeepVowels() : Keeps the vowels of a string.

Syntax
STR_KeepVowels( szString )  szNewString
Parameters
Returns
Example
? STR_KeepVowels( "Hello World" ) && "eoo"
STR_last() : Finds the last character that is not a space.

Syntax
STR_last( szString )  cChar
Parameters
szString string to find the last character from.
Returns
cChar last character that is not a space in szString . The string is processed from left to right.
Example
? STR_last( "Hello World" ) && "d"
? STR_last( "World " ) && "d"
See also
STR_first()
STR_LastVersion() : Returns the file stamp of STR functions.

Remark

String Functions
Syntax
STR_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\STRINGS.C-Mon Oct 19 15:55:22 1998" .
STR_Left() : Returns a specified number of characters from a

character expression, starting with the leftmost character.
Syntax
STR_Left( szString[,nCount] )  cResult
Parameters
nCount specifies the number of characters returned from the character expression. This parameter is
optional. If nCount is greater than the length of szString , an empty string is returned. If
nCount is not specified, only the leftmost character of szString is returned.
Returns
cResult the nCount leftmost characters of szString .
Example
? STR_Left("Hello" ) && "H"
? STR_Left("Hello",4 ) && "Hell"
STR_Length() : Determines the length of a string.

Alias
STR_len(), LENGTH()
Syntax
STR_Length( szString )  nLength
Parameters
szString string of which to determine length.
Returns
nLength length of the string.

String Functions
STR_Like() : Strings comparison with wildcards.
Remark
Although very similar, the STR_Like() function of FOCUS.FLL is not the same as the native LIKE() function of Visual
FoxPro. In many situations, both functions can complete each other. STR_like() is particularly easy to use to parse
long documents such as HTML pages or even source code.
Please remember that the STR_Like() function is case sensitive by default! If you want to perform comparisons
without regard to case, please issue STR_LikeCase( .F. ) .
Syntax
STR_Like( szToLookFor,[@]szToSearch[,nToken[,@nLastMatch[,nStart]]] )  nMatch
Parameters
szToLookFor the character expression to look for. Wildcards are permitted (* for any character, ? for a single
character).
szToSearch the character expression to search. This parameter can be sent by reference for better
performance (remains unchanged).
nToken optional token number (a token is either a "*" or a "?" placeholder).
nLastMatch optional last match position (MUST BE PASSED BY REFERENCE).
nStart optional starting position.
Returns
nMatch position where the match ends; 0 if no match is found.
Example
LOCAL szHTML
&& Example 1
m.szHTML = '<HTML><HEADER><TITLE>Hello World' + ;
'</TITLE></HEADER><BODY BGCOLOR="#FFFF00">This is the body</BODY></HTML>'
? STR_like("*<BODY>*</BODY>*",m.szHTML,2 ) && returns 0
? STR_like("*<BODY*>*</BODY>*",m.szHTML,2 ) && returns 96 because the end of the match

&& has been found at that position
&& We just asked the second token (second wildcard) which

&& is the settings of the BODY tag of the HTML page.
&& In this case ' BGCOLOR="#FFFF00"'
? STR_LikeGetToken() && BGCOLOR="#FFFF00"
? STR_like("*<BODY*>*</BODY>",m.szHTML,2 ) && returns 0 because no wildcard has

&& been specified at the end of the string
&& Example 2
&& This example searches an entire source code (.PRG) and locates
&& Change Control Tags so that they can be documented automatically
&& A Change Control tag has the following form:
&&
&& <cc date="20010520120000" auth="Anurak">
&& </cc date="20010520120000">
&& As you can see there is an opening tag, and a closing tag
&&
LOCAL szCode
LOCAL nStart
LOCAL nEnd
LOCAL nEnd2
LOCAL nMatch

String Functions
LOCAL szToken
LOCAL i
LOCAL szDateTime
LOCAL szAuthor
LOCAL szRef
LOCAL szComment
LOCAL nAtLine && Starting line
LOCAL nAtLine2 && Ending line
&& m.szFile is the .PRG file to read

m.szCode = FILETOSTR( m.szFile )
&& We won't use this variable but we need it for STR_like()

m.nMatch = 0
&& Staring position to start searching (STR_like())
m.nStart = 1
&& Without regard to case
STR_LikeCase( .F. )
WAIT WINDOW "Parsing the code. Please wait..." NOWAIT
IF ( ! EMPTY( m.szCode ) )
m.n
&& Process the entire string
DO WHILE ( .T. )
&& If we can find the opening tag … where does it end?

m.nEnd = STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,3,@nMatch,m.nStart )
&& Did we find the opening tag?

IF ( m.nEnd != 0 )
&& We found it … and because we asked FOCUS to store the 3rd placeholder
&& we now can simply extract the Date/Time value
m.szDateTime = STR_LikeGetToken()
&& That's the line number where we found the opening tag
m.nAtLine = STR_AtLine( m.nEnd,m.szCode )
&& Let's get the author name now

IF ( STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 )
m.szAuthor = STR_LikeGetToken()
ELSE
m.szAuthor = ""
ENDIF
&& Let's get an optional reference number (in case the Change Control
&& has been assigned such a number)
IF ( STR_Like( [*<cc*date="*"*ref="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 )
m.szRef = STR_LikeGetToken()
ELSE
m.szRef = ""
ENDIF
&& If we want to be exhaustive, we might as well

&& extract an optional comment (sounds a good idea)
IF ( STR_Like([*<cc*date="*"*comment="*"*>*],m.szCode,5,@nMatch,m.nStart) != 0 )
m.szComment = STR_LikeGetToken()
ELSE
m.szComment = ""
ENDIF
&& Let's remember where the oepning tag was ending … because,
&& this will be used to continue the scanning of the source code
m.nStart = m.nEnd
&& Searching for the closing tag now

m.nEnd2 = STR_Like( [*</cc*date="] + m.szDateTime + ;
[*>*],m.szCode,3,@nMatch,m.nEnd )
&& If we found it
IF ( m.nEnd2 != 0 )
&& To which line of the source code this tag belongs to?
m.nAtLine2 = STR_AtLine( m.nEnd2,m.szCode )
ELSE
m.nAtLine2 = -1
ENDIF

String Functions
&& Imagine we put what we found in a list control
&& OK, ok … we don't use the reference number nor do
&& we use the comment! But this is merely an example, right?
.lstCCtrl.AddItem( "CC Author: " + m.szAuthor + " -- " + ;
"Date : " + m.szDateTime + " -- " + ;
"Start:" + ALLTRIM( STR( m.nAtLine ) ) + " ... " + ;
"End:" + ALLTRIM( STR( m.nAtLine2 ) ) ;
)
ELSE
&& No opening tag found => we can exit the routine
EXIT
ENDIF
ENDDO
ENDIF
WAIT WINDOW "Done!" NOWAIT
STR_LikeCase() : Indicates whether STR_Like() should be case

sensitive or not (Get/Set function).
Remark
By default, STR_Like() is case sensitive! You can switch this off via the STR_LikeCase() function.
Syntax
STR_LikeCase( [lSetting] )  lOldSetting
Parameters
lSetting the new setting for STR_Like() . This parameter is optional. If not passed, the function simply
returns the current setting. .T. means case sensitive; .F. not.
Returns
lOldSetting old setting.
Example
LOCAL szHTML

STR_LikeCase( .T. ) && Should be case sensitive

? STR_like("*<body*>*</BODY>*",m.szHTML,2 ) && returns 0
STR_LikeCase( .F. ) && Without regard to case
? STR_like("*<body*>*</BODY>*",m.szHTML,2 ) && returns 96
STR_LikeGetToken() : Returns the last token specified when

using STR_Like().
Remark
This function can only be used AFTER a first call to STR_Like() .
Syntax
STR_LikeGetToken()  szToken

String Functions
Parameters
None.
Returns
szToken the specified token or an empty string is this token hasn't been found.
Example
LOCAL szHTML

? STR_like("*<BODY>*</BODY>*",m.szHTML,2 ) && returns 0
? STR_like("*<BODY*>*</BODY>*",m.szHTML,2 ) && returns 96 because the end of the match

&& has been found at that position
&& We just asked the second token (second wildcard) which

&& is the settings of the BODY tag of the HTML page.
&& In this case ' BGCOLOR="#FFFF00"'
? STR_LikeGetToken() && BGCOLOR="#FFFF00"
? STR_like("*<BODY*>*</BODY>",m.szHTML,2 ) && returns 0 because no wildcard has

&& been specified at the end of the string
STR_ltrim() : Returns the specified character expression with

leading blanks removed.
Syntax
STR_ltrim( szString )  szNewString
Parameters
Returns
szNewString string with leading blanks removed.
Example
LOCAl szString
m.szString = " Hello World "
? STR_ltrim( m.szString ) == LTRIM( m.szString ) && .T.
See Also
STR_TrimLeft() , STR_TrimRight()
STR_mirror() : Reverses a string.

Syntax
STR_mirror( szString )  szgnirtS
Parameters

String Functions
Returns
szgnirtS string mirrored.
Example
? STR_mirror( "Hello" ) && "olleH"
STR_MixUp() : Mix up a string.

Syntax
STR_MixUp( szString )  szMixUp
Parameters
Returns
szMixUp the string mixed up. STR_MixUp() can be successfully applied on its return value to retrieve
the original string. STR_MixUp() , when combined to other string functions of FOCUS.FLL , can
be used to encrypt strings.
Example
LOCAL szString
LOCAL szEncrypted
LOCAL szDecrypted
? STR_MixUp( "Hello" ) && "leHlo"
szString = "Hello World. Is everybody OK?"

szEncrypted = STR_MixUp( STR_shl( STR_mirror( STR_AddCod( szString,3 ) ),4 ) )
szDecrypted = STR_AddCod( STR_mirror( STR_shl( STR_MixUp( szEncrypted ),-4 ) ),-3 )
? ( szString == szDecrypted ) && .T.
? szEncrypted && "å$7&wÆW‡VÇ–d7‚Âv3÷¢%W7öö&„´

? szDecrypted && "Hello World. Is everybody OK?"
? LEN( szEncrypted ) && 29

? LEN( szDecrypted ) && 29
STR_n() : Extracts the nth character of a string.

Remark
This function is almost identical to STR_peek() but returns a character while STR_peek() returns a numeric.
Syntax
STR_n( szString,n )  cChar
Parameters
szString string to extract the nth character from.
n string offset.
Returns
cChar character that was extracted from szString . The first character has order 1.

String Functions
Example
? STR_n( "Hello World",7 ) && "W"
See also
STR_last(), STR_first()
STR_nparam() : Extracts the nth parameter of a string.

Remark
This function is useful when you need to parse strings that are used in Data Driven Applications.
Syntax
STR_nparam( szString,n )  szParam
Parameters
szString string to extract the nth parameter from.
n parameter number.
Returns
szParam character that was extracted from szString . The first character has order 1.
Example
? STR_nparam( "MyFunc(15,YourFunc(10,11,12),20",1 ) && "15"
? STR_nparam( "MyFunc(15,YourFunc(10,11,12),20",2 ) && "YourFunc(10,11,12)"
? STR_nparam( "MyFunc(15,YourFunc(10,11,12),20",2 ) && "20"
STR_npbrk() : Finds the 1st occurrence in a string of any

character from another string. Numeric result.
Syntax
STR_npbrk( szString1,szString2 )  nPosition
Parameters
szString1 string to be search for.
szString2 string to look for characters.
Returns
nPosition position of 1st occurrence of a character of szString2 in szString1
Example
? STR_npbrk( "The 3 men and 2 dogs ate 5 pigs","0123456789" ) && 5
STR_nset() : Set first n characters of string to specified

character.
Alias
STRNSET()

String Functions
Syntax
STR_nset( szString,cChar,n[,x] )  szNewString
Parameters
szString string to process (cannot contain embedded nulls CHR(0) ).
cChar character setting.
n number of characters to be set. If n is greater than the length of szString , the length of
szString is used instead of n.
x optional starting position.
Returns
szNewString altered string.
Example
&& Example 1
? STR_nset( "Hello World","B",4 ) && "BBBBo World"
&& Example 2
str2 = SPACE( 15 )
str = REPLICATE( "B",15 )
? str && "BBBBBBBBBBBBBBB"
? str2 && " "
? LEN( str ) && 15
? LEN( str2 ) && 15
str2 = str_nset( str,"A",3,4 ) && Set 3 characters starting at position 4
? str2 && "BBBAAABBBBBBBBB"
STR_ntoken() : Extracts a given token from a string.

Caution
Strings with embedded nulls cannot be processed by Token functions.
When you attempt to extract a given token, ensure that this token does really exist because no test is made to ensure
this from within the C and assembler routines. Trying to access a non existing token can produce unpredictable results.
Syntax
STR_ntoken( nToken,szString[,nStart] )  szToken
Parameters
nToken token number.
nStart starting position (optional parameter)
Returns
szToken desired token.
Example
LOCAL szOldSep
LOCAL szString
LOCAL nTokens
LOCAL i
szString = "Hello,Cat,Dog,Horse,Lion" && String to process

String Functions
szOldSep = STR_setsep( "," ) && Set internal sep.
nTokens = STR_numtok( szString ) && Number of tokens
&& Let's extract a given token

? STR_ntoken( 1,szString ) && "Hello"
? STR_ntoken( 4,szString ) && "Horse"
&& Let's extract ALL tokens

FOR i = 1 TO nTokens && Process all tokens
? STR_ntoken( i,szString ) && Extract given token
NEXT
STR_setsep( szOldSep ) && Reset separator
STR_null() : Returns a null string (empty string).

Comment
This function can be used with nested functions to get rid of a return value. See also MIS_true() and
MIS_false() .
Syntax
STR_null()  ""
Parameters
None.
Returns
"" empty string.
STR_numtok() : Determines the number of tokens in a string.

Caution
Alias
NumberOfTokens()
Syntax
STR_numtok( szString[,nStart] )  nTokens
Parameters
nStart starting position (optional parameter)
Returns
nTokens number of tokens based on the internal separator.
Example
LOCAL szOldSep
LOCAL szString
LOCAL nTokens
LOCAL i

String Functions
&& Let's extract a given token

? STR_ntoken( 1,szString ) && "Hello"
&& Let's extract ALL tokens

NEXT
STR_setsep( szOldSep ) && Reset separator
STR_occu() : Determines position of nth occurrence of a

character in a string.
Syntax
STR_occu( szString,cChar,nOccurrence )  nPosition
Parameters
cChar character to look for.
nOccurrence occurrence to pay attention to.
Returns
nPosition position where the nOccurrence of cChar was found in szString .
STR_peek() : Returns the ASCII code of a given character in a

string.
Syntax
STR_peek( szString,nPosition )  nCode
Parameters
nPosition position in string to examine.
Returns
nCode ASCII code value of the character found at nPosition in szString .
Example
? STR_peek( "Hello",1 ) && 72 because 'H' is 72
See also
STR_n() , STR_poke()

String Functions
STR_poke() : Poke a character at given position in string.
Syntax
STR_poke( szString,nPosition,nCode )  szResult
Parameters
nPosition position in string to examine.
nCode ASCII code to stuff at the proper position.
Returns
Example
szString = "Hello"
? STR_poke( szString,2,97 ) && "Hallo"
? szString && "Hello"
See also
STR_peek()
STR_Proper() : Returns a string capitalized appropriately for

proper names.
Syntax
STR_Proper( szString,szSpecialChars )  szProper
Parameters
szSpecialChars characters that should force an uppercase of the next letter. Usually, these characters are
" ","'","." ,"-".
Returns
szProper resulting string.
Potential problem
When STR_Proper() treats a character string, it cannot distinguish between characters that must be especially kept
lowercase as it appears in names such as "Jan de la Court" where "de la" should be especially kept as it is.
Therefore, STR_Proper() will use the special character "\" to force an unchanged letter. The way to keep "JAN DE
LA COURT" being properly uppercased is to pass the following string "JAN \DE \LA COURT" . This is forcing the
following result "Jan de la Court" .
All characters that are preceded by a backslash are rendered as they appear in the original string.
Example
LOCAL szName
szName = "Jean-Claude d'Haese"

String Functions
? STR_Proper( LOWER( szName ) ," -'" ) && "Jean-Claude D'Haese"
? STR_Proper( "JEAN-CLAUDE D'HAESE" ," -'" ) && "Jean-Claude D'Haese"
? STR_Proper( "JEAN-CLAUDE \d'HAESE"," -'" ) && "Jean-Claude d'Haese"
STR_raw() : Forms a string of characters comprised between a

given ASCII range.
Remark
Don't include the CHR(0) in the range of characters to form the raw string. A CHR(0) is treated as the end of the
string in C and will therefore not produce the expected result. Should you want to include the CHR(0) char in the set
of characters, then simply add it in native FoxPro with a concatenation operation.
The STR_raw() function is really handy to replace strings formed of a character range. For example the
STR_raw( 1,5 ) is strictly equivalent to CHR(1)+CHR(2)+CHR(3)+CHR(4)+CHR(5) .
Syntax
STR_raw( nRangeIn,nRangeOut )  szString
Parameters
nRangeIn starting range.
nRangeOut ending range.
Returns
szString the character string is formed with all the ASCII characters comprised within ASCII nRangeIn
and ASCII nRangeOut .
Example
? STR_raw( 1,5 ) == CHR(1)+CHR(2)+CHR(3)+CHR(4)+CHR(5) && .T.
STR_reduce() : Reduces consecutive occurrences of the same

character to only 1 occurrence.
Syntax
STR_reduce( szString,cChar )  szNewString
Parameters
cChar character for which reduces consecutive occurrences to only 1 occurrence.
Returns
Example
? STR_reduce("Hello WWWorld","W" ) // "Hello World"

String Functions
STR_relin() : Run Encoding Length algorithm (In).
Comment
This function is very useful to compress text files where many occurrences of the same character appear in a
consecutive order.
Syntax
STR_relin( szString )  szNewString
Parameters
Returns
Example
? STR_relin( "Hellllllllllo World" )
&& The multiple l in "Hellllllllllo World" will be reduced to 3
&& characters (first one is CHR(1), second is the number of
&& occurrences, third is the character that should be repeated
STR_relout() : Run Encoding Length algorithm (Out).

Syntax
STR_relout( szString )  szOriString
Parameters
Returns
szOriString resulting string.
Example
szString = "Hellllllllllo World"
? STR_relout( STR_relin( szString ) ) && "Hellllllllllo World"
STR_Replace() : Replaces a substring with another in a string.

Syntax
STR_Replace( szString,szExprSought,szReplacement )  szResult
Parameters
szExpSought character expression that is searched for in szString . The search is case-sensitive.
szReplacement character expression that replaces every occurrence of szExpSought in szString .

String Functions
Returns
Example
STR_Replace( "Hello Pat","Pat","Martin" ) && "Hello Martin"
STR_ResetLikeCharConversions() : Resets the conversion

table for STR_Like().
Remark
STR_Like() is capable to match strings for which some loose pattern matching is required. For example, if you want
that "Sammy" matches "Fanny" , it's enough to state that "S" equals "F" and "m" equals "n" . Such character
conversions can be specified with STR_SetLikeCharConversion() . When character conversions are no longer
needed, the developer can use the STR_ResetLikeCharConversions() to reset the internal table to its original
state.
Syntax
STR_ResetLikeCharConversions()  .T.
Parameters
None.
Returns
.T. the function returns always .T. .
Example
? STR_Like( "*Sammy*","Fanny was here." ) && 0
STR_SetLikeCharConversion( "S","F" )
STR_SetLikeCharConversion( "m","n" )
STR_ResetLikeCharConversions()
STR_Right() : Returns a specified number of characters from a

character expression, starting with the rightmost
character.
Syntax
STR_Right( szString[,nCount] )  szResult
Parameters
nCount specifies the number of characters returned from the character expression. This parameter is
optional. If nCount is greater than the length of szString , an empty string is returned. If
nCount is not specified, only the rightmost character of szString is returned.

String Functions
Returns
szResult the nCount rightmost characters of szString .
Example
? STR_Right("Hello" ) && "o"
? STR_Right("Hello",4 ) && "ello"
STR_rtrim() : Returns the specified character expression with

trailing blanks removed.
Syntax
STR_rtrim( szString )  szNewString
Parameters
Returns
szNewString string with trailing blanks removed.
Example
LOCAl szString
m.szString = " Hello World "
? STR_rtrim( m.szString ) == RTRIM( m.szString ) && .T.
STR_SetCharConversion() : Gets/sets a new character

conversion for STR_ConvertA2B() and STR_ConvertB2A().
Remark
STR_SetCharConversion() provides additional flexibility to the STR_SetConvTable() function to issue
character conversions.
Syntax
STR_SetCharConversion( iChar1,iChar2 )  lSuccess
Parameters
iChar1 character for which a conversion needs to take place.
iChar2 every occurrence of iChar1 should be converted to iChar2 .
Returns
.T. .T.. if the function is successful; .F. if not.
Example
LOCAL iCharH,iCharW
LOCAL szString


String Functions


See also
STR_ConvertA2B() , STR_ConvertB2A() , STR_SetConvTable() .
STR_SetConvTable() : Sets a conversion table for

STR_ConvertA2B() and STR_ConvertB2A().
Remark
The STR_SetConvTable() function can be used in conjunction with the STR_ConvertA2B() and
STR_ConvertB2A() . To give additional flexibility, the STR_SetCharConversion() (not to be confused with
STR_SetLikeCharConversion() ) can be used to adapt a conversion for a single character.
transformations.
Syntax
STR_SetConvTable( @aConv )  lResult
Parameters
aConv a 256 elements array (MUST be passed by reference). Each cell of the array contains the value
that must be applied for the conversion. The position itself (array index) is associated to the
character for which a conversion must take place (be careful … position 1 in the array is
associated with CHR(0) ).
Returns
lResult .T. if function is successful, .F. if not.
Example
LOCAL ARRAY aConv[256]
<Je devrais reprendre l'exemple d'une table de conversion EBCDIC comme dans le conversion.txt>
FOR i = 1 TO 256
aConv[i] = <ICI JE DOIS CONTINUER>
NEXT
See also
STR_ConvertA2B() , STR_ConvertB2A() , STR_SetCharConversion() .
STR_SetLikeCharConversion() : Gets/sets a new character

conversion for STR_Like().
Remark
STR_Like() is capable to match strings for which some loose pattern matching is required. For example, if you want
that "Sammy" matches "Fanny" , it's enough to state that "S" equals "F" and "m" equals "n" . Such character
conversions can be specified with STR_SetLikeCharConversion() .

String Functions
Syntax
STR_SetLikeCharConversion( cChar1,cChar2 )  .T.
Parameters
cChar1 character for which a conversion needs to take place.
cChar2 every occurrence of cChar1 will be treated as if it was cChar2 .
Returns
.T. the function returns always .T. .
Example
STR_SetLikeCharConversion( "S","F" )
STR_SetLikeCharConversion( "m","n" )
STR_setoff() : Sets the internal offset position of token

functions.
Comment
STR_setoff() is one of the token functions. This function is intended to be used when accessing one token after
another. In this sense, tokens are not reached at random. STR_setoff() posts the internal counter Offset.
Syntax
STR_setoff( nOffset )  .T.
Parameters
nOffset new value to post into the internal counter Offset. Extra caution ... you can easily fool this
function and consequently STR_toknex() will yield unpredictable results.
Returns
.T. the function always returns a logical .T.
STR_setsep() : Gets/sets the internal separator for token based

functions.
Caution
Syntax
STR_setsep( szSeparators )  szOldSeparators
Parameters
szSeparators new separators to use. By default the current separators is ",". You can use a multiple
separators such as ",;:.()/" .

String Functions
Returns
szOldSeparators current separators.
Example
LOCAL szOldSep
LOCAL szString
LOCAL nTokens
LOCAL i


NEXT
STR_setsep( szOldSep ) && Reset the separator to what it was
STR_shl() : Shifts-Left a string by a given number of bits.

Comment
STR_shl() can be one useful component of an encryption algorithm. STR_shr() is the opposite function and can be
used to restore a string to its original value.
Syntax
STR_shl( szString,nBits )  szNewString
Parameters
nBits number of bits to shift the string by. Minimum 1 bit, maximum 7 bits. If you pass a negative
number, the function acts as its contrary STR_shr() .
Returns
szNewString shifted string.
STR_shr() : Shifts-Right a string by a given number of bits.

Comment
STR_shr() can be one useful component of an encryption algorithm. STR_shl() is the opposite function and can be
used to restore a string to its original value.
Syntax
STR_shr( szString,nBits )  szNewString
Parameters
nBits number of bits to shift the string by. Minimum 1 bit, maximum 7 bits. If you pass a negative
number, the function acts as its contrary STR_shl() .

String Functions
Returns
szNewString shifted string.
STR_sort() : Sorts all the characters in a string.

Caution
Strings with embedded nulls are not supported.
Syntax
STR_sort( szStr )  szSorted
Parameters
szStr string to process.
Returns
szSorted szStr sorted.
Example
? STR_sort( "Hello World" ) && "Hwdellloor"
STR_soundex() : Returns a phonetic key reprsenting a name.

Remark
The STR_soundex() function of FOCUS.FLL isn't as fast as the native SOUNDEX() function of Visual FoxPro (due to
the fact that strings are really recopied with the FoxPro API to C). But it works better for real names as it does not
discriminate the first letter of the word. For example, SOUNDEX() is fooled with the following test:
? SOUNDEX( "HULRICH MEYER" ) == SOUNDEX("ULRICH MAIER" ) && .F.

? STR_soundex( "HULRICH MEYER" ) == STR_soundex("ULRICH MAIER" ) && .T.
Syntax
STR_Soundex( szString )  nResult
Parameters
Returns
nResult phonetic key representing szString .
Example
&& If the name of that terrorist appears in the text, I won't miss it
? STR_soundex( "Ousama Bin Ladin" ) == STR_soundex( "Usama Ben Laden" ) && .T.
? STR_soundex( "Ousamma BinLadin" ) == STR_soundex( "Usama ben Laten" ) && .T.
STR_start() : Does a string start with a given value?

Syntax
STR_start( szString1,szString2 )  lResult

String Functions
Parameters
szString1 string to process.
szString2 string to look for.
Returns
lResult .T. if szString1 starts with szString2 .
Example
? STR_start( "L'Année du dragon","L'" ) && .T.
See also
STR_end()
STR_strip() : Strips characters in a given range from a

character string.
Syntax
STR_strip( szString,nRangeIn,nRangeOut )  szNewString
Parameters
nRangeIn starting range.
nRangeOut ending range.
Returns
szNewString szString without any character comprised within ASCII nRangeIn and ASCII nRangeOut .
Example
? STR_strip( szString,0,31 ) && Eliminates all chars between ASCII 0 and 31
STR_strtok() : Extracts a token from a string.

Syntax
STR_strtok( n,szString,szSeparators )  szToken
Parameters
n token number.
szSeparators string of separators.
Returns
szToken extracted token.

String Functions
Example
? STR_strtok( 1,"Hello World"," " ) && "Hello"
See also
STR_end()
STR_TillNull() : Returns a string up to the first null character.

Syntax
STR_TillNull( szString )  szResult
Parameters
szString the string to process. Usually this strings contains null characters.
Returns
szResult the stripped string. The function does not strip all null characters. It merely returns a substring
up to the first null of szString .
Example
LOCAL szString
szString = REPLICATE( CHR(0),20 )
szString = "Hello" + szString
? STR_TillNull( szString ) && "Hello", all CHR(0) are stripped !
STR_tokfin() : Did we process the entire string?

Caution
Comment
STR_tokfin() is one of the token functions. This function is intended to be used to know if we processed entirely a
string with STR_toknex() .
Syntax
STR_tokfin()  lEnd
Parameters
None.
Returns
lEnd indicates whether we processed the entire token string.

String Functions
Example
LOCAL szString
LOCAL szToken
szString = "Hello all of you. Are you OK? What's your name? Mine is Pat"
STR_setsep( " .,;?" ) && Separators to be considered
STR_tokini( szString ) && Initialize the string
CLEAR
? "Begin>>>" && Show when we start
DO WHILE ( ! STR_tokfin() ) && While not end of processing

szToken = STR_toknex() && Extract the token
IF ( ! EMPTY( szToken ) ) && If the token is not empty
? szToken && Let's display it
ENDIF
ENDDO
? "<<<End" && Show when we end
See Also
STR_tokini() , STR_toknex() .
STR_tokini() : Initializes internal counters for token

processing.
Comment
STR_tokini() is one of the token functions. This function is intended to be used when accessing one token after
another. In this sense, tokens are not reached at random. STR_tokini() initializes the internal counters. IT MUST
BE USED prior to any SCR_toknex() function call.
Syntax
STR_tokini( szString )  .T.
Parameters
szString the string to be processed.
Returns
Example
LOCAL szString
LOCAL szToken
CLEAR

ENDIF
ENDDO

String Functions
See Also
STR_tokfin() , STR_toknex() .
STR_toknex() : Gets the next token.

Comment
STR_toknex() is the chore function of optimized token functions. It uses the internal separator.
Syntax
STR_toknex( szString )  szToken
Parameters
szString string from which the next token has to be extracted.
Returns
szToken next token available in stream.
Example
LOCAL szString
LOCAL szToken
CLEAR

ENDIF
ENDDO
See Also
STR_tokini() , STR_tokfin() .
STR_tokpos() : Determines the starting position of a given

token.
Syntax
STR_tokpos( nToken,szString )  nPosition
Parameters
nToken token number.

String Functions
Returns
nPosition starting position of the given token.
Example
LOCAL cOldSep
LOCAL szString
szString = "Cat,Dog,Horse,Lion" && String to process

cOldSep = STR_setsep( "," ) && Set separator to ","
? STR_tokpos( 4,szString ) && 15
STR_setsep( cOldSep )
Caution
When you attempt to determine the starting position of a given token, ensure that this token does really exist because
no test is made to ensure this from within the C and assembler routines. Trying to access a non existing token can
produce unpredictable results.
STR_TrimLeft() : Trims off x characters from the left of a string.

Syntax
STR_TrimLeft ( szString,n )  szNewString
Parameters
n characters count.
Returns
szNewString output string.
Example
LOCAl szString
m.szString = "ABCDE"
? STR_TrimLeft( "ABCDE",1 ) && "BCDE"
See Also
STR_LTrim() , STR_RTrim() , STR_TrimRight()
STR_TrimRight() : Trims off x characters from the right of a

string.
Syntax
STR_TrimRight ( szString,n )  szNewString
Parameters
n characters count.

String Functions
Returns
szNewString output string.
Example
LOCAl szString
m.szString = "ABCDE"
? STR_TrimRight( "ABCDE",1 ) && "ABCD"
See Also
STR_LTrim() , STR_RTrim() , STR_TrimRight()

System Functions
System Functions

System Functions
SYS_ACLineStatus() : AC power status.

Alias
ACLineStatus()
Syntax
SYS_ACLineStatus()  nStatus
Parameters
None.
Returns
nStatus AC power status. This parameter can be one of the following values:
Value Description
0 Offline
1 Online
255 Unknown status
SYS_AllocConsole() : Allocates a new console to the current

program (EXE).
Syntax
SYS_AllocConsole( [szTitle] )  nSuccess
Parameters
szTitle title of the new console window. This parameter is optional.
Returns
nSuccess 1 if the function is entirely successful; -1 if the function is partially successful; 0 if failure.
Example
SYS_FreeConsole() && Free the current console if any
IF ( SYS_AllocConsole( "My Easy Debugging Window" ) != 0 )

&& Let's write the name of the program that is currently executed
SYS_WriteConsole( DTOS( DATE() ) + " at " + TIME() + ":" + ;
PROGRAM(0) + " is executing" + CHR(13) + CHR(10) )
ENDIF
&& Close the console when you're done

SYS_FreeConsole()
SYS_avaclu() : Gets the number of available clusters on disk.

Alias
AvailableClusters()
Syntax
SYS_avaclu( szDrive )  nClusters

System Functions
Parameters
szDrive drive letter from which to obtain the number of available clusters.
Returns
nClusters number of available clusters.
Example
LOCAL nClusters
LOCAL nSectors
LOCAL nBytes
LOCAL szDrive
szDrive = SYS_curdri() + ":\"
nClusters = SYS_avaclu( szDrive )

nSectors = SYS_secclu( szDrive )
nBytes = SYS_bytsec( szDrive )
? "Available disk space : ", nClusters * nSectors * nBytes
See also
SYS_totclu()
SYS_BatteryFlag() : Battery charge status.

Alias
BatteryFlag()
Syntax
SYS_BatteryFlag()  nStatus
Parameters
None.
Returns
nStatus battery charge status. This parameter can be a combination of the following values:
Value Description
1 High
2 Low
4 Critical
8 Charging
128 No system battery
255 Unknown status
On Windows NT 4.0 this function returned 0. It is not documented anywhere what this value
means.
SYS_BatteryFullLifeTime() : Number of seconds of battery life

when at full charge.
Alias
BatteryFullLifeTime()

System Functions
Syntax
SYS_BatteryFullLifeTime()  nSeconds
Parameters
None.
Returns
nStatus number of seconds of battery life when at full charge, or
-1 if full lifetime is unknown.
SYS_BatteryLifePercent() : Percentage of full battery charge

remaining.
Alias
BatteryLifePercent()
Syntax
SYS_BatteryLifePercent()  nPercent
Parameters
None.
Returns
nPercent percentage of full battery charge remaining. It can be a value in the range 0 to 100, or 255 if
status is unknown.
SYS_BatteryLifeTime() : Number of seconds of battery life

remaining.
Alias
BatteryLifeTime()
Syntax
SYS_BatteryLifeTime()  nSeconds
Parameters
None.
Returns
nSeconds number of seconds of battery life remaining, or -1 if remaining seconds are unknown.
SYS_Broadcast() : Broadcasts a WIN.INI change to all

applications.
Alias
Broadcast()

System Functions
Syntax
SYS_Broadcast( szSetting )  .T.
Parameters
szSetting setting that has changed.
Returns
SYS_bytsec() : Gets the number of bytes per sector on given

disk
Alias
BytesPerSector()
Syntax
SYS_bytsec( szDrive )  nBytes
Parameters
szDrive drive letter from which to obtain the number of bytes per sector.
Returns
nBytes number of bytes per sector.
Example
LOCAL nClusters
LOCAL nSectors
LOCAL nBytes
LOCAL szDrive

See also
SYS_totclu(), SYS_avaclu(), SYS_secclu()
SYS_ConfigurePort() : Displays the port-configuration dialog

box for a port.
Remark
This function is not supported in NT 4.
Syntax
SYS_ConfigurePort( szPort )  .T.

System Functions
Parameters
szPort port to be configured.
Returns
Examples
? SYS_ConfigurePort( "LPT1" )
* Displays the following dialog
? SYS_ConfigurePort( "COM1" )
* Displays the following dialogs

System Functions
SYS_GetConsoleHWND() : Returns the Windows handle of the

current console.
Syntax
SYS_GetConsoleHWND()  nHwnd
Parameters
None.
Returns
nHwnd 0 if the function is not successful; otherwise the window handle (HWND).

System Functions
SYS_GetConsoleTitle() : Gets the title of the current console.
Syntax
SYS_GetConsoleTitle()  szTitle
Parameters
None
Returns
szTitle Title of the console window.
Example
&& If we can allocate a new console
IF ( SYS_AllocConsole( "FOCUS Debugging Window" ) != 0 )
? SYS_GetConsoleTitle() && Should be "FOCUS Debugging Window"
SYS_SetConsoleTitle( "My new debugging window" )
ENDIF
SYS_CreateMutex() : Creates a named mutex object.

Remark
A very easy way to check whether an instance of an application is already in memory is to create a named mutex. In
an application you first test whether a given mutex exists, if not, you create it. If it exists, that means that the
application is already running. A mutex is automatically destroyed when the application that created it is exited.
Alias
CreateMutex()
Syntax
SYS_CreateMutex( szMutex )  nMutexHandle
Parameters
szMutex string indicating the mutex name.
Returns
nMutexHandle handle to the mutex object.
Remark
A very easy way to check whether an Instance of an application is already in memory is to create a named mutex. In
application is already running.
Example
&& This example checks whether a given mutex already exists;
&& if it exists, it means that this application is in memory,
&& and consequently, already unloads
IF ( ! SYS_isMutex( "UniqueMutex" ) )
SYS_CreateMutex( "UniqueMutex" )
ELSE
QUIT
ENDIF

System Functions
See also
SYS_isMutex() , SYS_DeleteMutex()
SYS_curdri() : Obtains the current drive.

Syntax
SYS_curdri()  szDrive
Parameters
None.
Returns
szDrive current system drive. This function differs from FoxPro built-in SYS(5) which returns the SET
DEFAULT TO setting, even though under normal circumstances this should be the same.
Example
? "Current drive = " + SYS_curdri()
SYS_DeleteMutex() : Releases mutex object.

Remark
Alias
DeleteMutex()
Syntax
SYS_DeleteMutex( nMutexHandle )  lSuccess
Parameters
nMutexHandle handle to the mutex object.
Returns
lSuccess .T. if the operation was successful; .F. if not.
See also
SYS_isMutex() , SYS_CreateMutex()
SYS_displa() : Returns the display driver which is used by

Windows.
Syntax
SYS_displa()  szDisplayDrv

System Functions
Parameters
None.
Returns
szDisplayDrv display driver used by the system.
Example
* This could be used in an About dialog box
? "Display driver : ",SYS_displa()
SYS_DoesDriveExist() : Finds out if given drive exists in the

system.
Syntax
SYS_DoesDriveExist( szDrive )  lExist
Parameters
szDrive drive to test for existence.
Returns
lExist .T. if <szDrive> exists, .F. otherwise.
SYS_DoesSupportCompression() : Does the file system

support file-based compression.
Syntax
SYS_DoesSupportCompression( szRootDir )  lCompression
Parameters
szRootDir root directory of drive to obtain information from.
Returns
lCompression .T. if file system supports compression, .F. otherwise.
SYS_dosmaj() : Returns DOS major version number.

Alias
DosMaj(), DosMajor()
Syntax
SYS_dosmaj()  nMajor
Parameters
None.

System Functions
Returns
nMajor DOS major version number.
Example
? "DOS ver : " + LTRIM(STR(SYS_dosmaj())) + "." + LTRIM(STR(SYS_dosmin()))
SYS_dosmin() : Returns DOS minor version number.

Alias
DosMin(), DosMinor()
Syntax
SYS_dosmin()  nMinor
Parameters
None.
Returns
nMinor DOS minor version number.
Example
? "DOS ver : " + LTRIM(STR(SYS_dosmaj())) + "." + LTRIM(STR(SYS_dosmin()))
SYS_dristr() : Returns a string with all drives.

Syntax
SYS_dristr()  szString
Parameters
None.
Returns
szString string where all available drives are listed.
Example
szDriveStr = SYS_dristr()
? "Your system has " + ALLTRIM( STR( LEN( szDriveStr ) ) ) + ;

" drives"
SYS_DriveType() : Returns the drive type.

Alias
DriveType()
Syntax
SYS_DriveType( szDriveRoot )  nType

System Functions
Parameters
szDriveRoot root directory of drive.
Returns
nType drive type.
#define DRIVE_UNKNOWN 0
#define DRIVE_NO_ROOT_DIR 1
#define DRIVE_REMOVABLE 2
#define DRIVE_FIXED 3
#define DRIVE_REMOTE 4
#define DRIVE_CDROM 5
#define DRIVE_RAMDISK 6
See also
SYS_iscd() , SYS_isflop() , SYS_isfixe() , SYS_isremo() , SYS_isram()
SYS_dsksiz() : Returns the total capacity in bytes of a

specified disk drive.
Remark
Windows 95: For volumes that are larger than 2 gigabytes, the GetDiskFreeSpace() function may return
misleading values (this function is used internally by FOCUS.FLL to determine the size of the drive). The function caps
the values stored into some of the parameters ( lpNumberOfFreeClusters and lpTotalNumberOfClusters ) so
as to never report volume sizes that are greater than 2 gigabytes!
Even on volumes that are smaller than 2 gigabytes, the values stored into lpSectorsPerCluster ,
lpNumberOfFreeClusters , and lpTotalNumberOfClusters values may be incorrect. That is because the
operating system manipulates the values so that computations with them yield the correct volume size.
Windows 95 OSR2 and Windows 98: The GetDiskFreeSpaceEx() function is available beginning with Windows
95 OEM Service Release 2 (OSR2), and it should be used whenever possible. The GetDiskFreeSpaceEx() function
returns correct values for all volumes, including those that are larger than 2 gigabytes.
Windows NT and Windows 2000: GetDiskFreeSpaceEx() is available on Windows NT version 4.0 and higher,
including Windows 2000.
FOCUS.FLL will use GetDiskFreeSpaceEx() if possible; in other cases it will turn down to
GetDiskFreeSpace() . The code of FOCUS.FLL has changed due to the remark of Paul Newton which also made all
the necessary research to help us fix the problem.
Alias
DiskSize(), SYS_DiskSize()
Syntax
SYS_dsksiz( szDrive )  nBytes
Parameters
szDrive drive to test. It can be a full pathname with a drive specifier since only the first character is
checked.
Return
nBytes total capacity of szDrive .

System Functions
Example
? SYS_dsksiz( SYS_curdri() + ":\" )
See also
? SYS_dskspa()
SYS_dskspa() : Returns the number of available bytes on a

given disk drive
Windows 95: For volumes that are larger than 2 gigabytes, the GetDiskFreeSpace() function may return
misleading values (this function is used internally by FOCUS.FLL to determine the size of the drive). The function caps
the values stored into some of the parameters ( lpNumberOfFreeClusters and lpTotalNumberOfClusters ) so
as to never report volume sizes that are greater than 2 gigabytes!
Even on volumes that are smaller than 2 gigabytes, the values stored into lpSectorsPerCluster ,
lpNumberOfFreeClusters , and lpTotalNumberOfClusters values may be incorrect. That is because the
operating system manipulates the values so that computations with them yield the correct volume size.
Windows 95 OSR2 and Windows 98: The GetDiskFreeSpaceEx() function is available beginning with Windows
95 OEM Service Release 2 (OSR2), and it should be used whenever possible. The GetDiskFreeSpaceEx() function
returns correct values for all volumes, including those that are larger than 2 gigabytes.
Windows NT and Windows 2000: GetDiskFreeSpaceEx() is available on Windows NT version 4.0 and higher,
including Windows 2000.
FOCUS.FLL will use GetDiskFreeSpaceEx() if possible; in other cases it will turn down to
GetDiskFreeSpace() . The code of FOCUS.FLL has changed due to the remark of Paul Newton which also made all
the necessary research to help us fix the problem.
Alias
DiskRoom(), SYS_DiskSpace(), SYS_DiskSpaceLeft(), SYS_DiskEmpty()
Syntax
SYS_dskspa( szDrive )  nBytes
Parameters
szDrive drive to test. It can be a full pathname with a drive specifier since only the first character is
checked.
Return
nBytes number of available bytes on the specific drive. This function is useful for determining whether
sufficient space is available on a given drive. It differs from FoxPro DISKSPACE() in that it
allows the developer to specify which drive has to be checked while FoxPro only checks for the
current drive.
Example
? SYS_dskspa( SYS_curdri() + ":\" )
See also
? SYS_dsksiz()

System Functions
SYS_EnumDeviceDrivers() : List of active device drivers in the
system
Comment
Please notice that SYS_EnumDeviceDrivers() operates do not work under Windows 9x: it needs Windows
NT as it uses the psapi.dll. This DLL isn't always distributed with Windows.
You can use the DLL Help Database of Microsoft. The DLL Help exists to assist developers, system administrators, and other
IT professionals who face file version conflicts with Microsoft software. Use DLL Help to identify which software installed a
specific version of a DLL (http://support.microsoft.com/servicedesks/fileversion/dllinfo.asp?sd=MSDN).
Alias
EnumDeviceDrivers()
Syntax
SYS_EnumDeviceDrivers()  szList
Parameters
nAppTypes optional parameter: 0 by default. Can be 16 if you want to list 16-bit applications, or 32 for 32-
bit applications. This parameter is completely ignored when the function operates on the
Windows NT platform.
Returns
szList list of all active tasks running on the system. Each task is separated by each other by a caret
(^) like in this example :
"KERNEL32.DLL(32-bit)^MSGSRV32(16-bit)^MPREXE.EXE(32-bit)^VSHWIN32.EXE(32-
bit)^MMTASK(16-bit)ÊXPLORER.EXE(32-bit)^POINTEXE(16-bit)^SYSTRAY.EXE(32-
bit)^SAGE.EXE(32-bit)ÎNTERNAT.EXE(32-bit)^FINDFAST.EXE(32-bit)^SPOOL32.EXE(32-
bit)ÎNFOVIEW.EXE(32-bit)^MSVC.EXE(32-bit)^WINOLDAP(16-bit)^VFP.EXE(32-
bit)^CTCD(16-bit)^WINWORD.EXE(32-bit)"
When no parameter has been passed to the function, or when this parameter was 0, then each
process is clearly shown as a 32-bit or 16-bit process when run under Windows 9x. When run in
NT, the function does not add any process information (16-bit or 32-bit).
Example
? SYS_Processes() under Windows 95 or Windows 98 (Windows 9x)
&& KERNEL32.DLL(32-bit)^MSGSRV32(16-bit)^MPREXE.EXE(32-bit)^VSHWIN32.EXE(32-
&& bit)^MMTASK(16-bit)ÊXPLORER.EXE(32-bit)^POINTEXE(16-bit)^SYSTRAY.EXE(32-
&& bit)^SAGE.EXE(32-bit)ÎNTERNAT.EXE(32-bit)^FINDFAST.EXE(32-bit)^SPOOL32.EXE(32-
&& bit)ÎNFOVIEW.EXE(32-bit)^MSVC.EXE(32-bit)^WINOLDAP(16-bit)^VFP.EXE(32-
&& bit)^CTCD(16-bit)^WINWORD.EXE(32-bit)
? SYS_Processes(16) under Windows 95 or Windows 98 (Windows 9x)

&& MSGSRV32^MMTASK^POINTEXE^WINOLDAP^CTCD

&& KERNEL32.DLL^MPREXE.EXE^VSHWIN32.EXEÊXPLORER.EXE^SYSTRAY.EXE^SAGE.EXE^
&& INTERNAT.EXE^FINDFAST.EXE^SPOOL32.EXEÎNFOVIEW.EXE^MSVC.EXE^VFP.EXE^WINWORD.EXE
? SYS_Processes() under Window NT (here Windows 2000 Professional)

smss.exe^winlogon.exe^services.exe^lsass.exe^svchost.exe^spoolsv.exe^svchost.exe^mdm.exeÂMQSVC.EXE^
navapsvc.exeâmqmsrvn.exe^npssvc.exe^jview.exe^regsvc.exe^MSTask.exe^WinMgmt.exeÊxplorer.EXEâmqzxm
a0.exeâmqxssvn.exeâmqxssvn.exeâmqharmn.exeâmqhasmn.exeâtiptaxx.exe^POProxy.exe^Winampa.exeînte
rnat.exe^navapw32.exeÂcroTray.exeâmqmtbrn.exeâmqzllp0.exe^np.exeâmqrrmfa.exeâmqzlaa0.exeÂMQPCS
EA.EXE^RUNMQCHI.exeâmqxssvn.exe^RUNMQLSR.exeâmqzxma0.exeâmqxssvn.exeâmqxssvn.exeâmqhasmn.exeâm
qzllp0.exeâmqrrmfa.exeâmqzlaa0.exeÂMQPCSEA.EXE^RUNMQCHI.exe^RUNMQLSR.exeâlertsvc.exe^WINCMD32.EX
E^WINCMD32.EXE^psdk-
x86.exe^WebSetup.exe^msiexec.exe^msiexec.exeîmages2100.exe^WINCMD32.EXE^WINWORD.EXE^VFP6.EXE

System Functions
See also
SYS_tasks(), SYS_EnumDeviceDrivers()
SYS_errhan() : Custom Windows error handling

Syntax
SYS_errhan( nNewHandlerLevel )  nOldHandlerLevel
Parameters
nNewHandlerLevel new level of Windows error handling.
SEM_FAILCRITICALERRORS = 0x0001 Windows does not display the critical-error-handler

message box and returns the error to the calling
application.
SEM_NOGPFAULTERRORBOX = 0x0002 Windows does not display the general-protection-fault
message box. This flag should be set only by debugging
applications that handle GP faults themselves.
SEM_NOOPENFILEERRORBOX = 0x8000 Windows does not display a message box when it fails to
find a file.
Returns
nOldHandlerLevel old level of Windows error handling.
Caution
Be extra careful when using this function because it supersedes Windows default behavior.
SYS_exenam() : Returns the executable file name

Alias
SYS_RealExeName(), SYS_RealExecutableName(), ExecutableName(), FIL_exenam()
Syntax
SYS_exenam()  szExeName
Parameters
None.
Returns
szExeName name of the current executable.
Example
? FIL_exenam()
? SYS_exenam()
? SYS( 16,0 )
Alternatives
Try SYS(16,0) to get the real .EXE name.

System Functions
SYS_ExitProcess() : Ends a process and all of its threads.
Comment
This function specifies the exit code for the process and for all threads that are terminated as a result of this call.
GetExitCodeProcess() function to retrieve the process's exit value. Use the GetExitCodeThread() function to
retrieve a thread's exit value.
Syntax
SYS_ExitProcess( nLevel )  you never return from this function
Parameters
nLevel the error level to return to calling application or command file.
Returns
None.
Example
SYS_ExitProcess( 115 ) && 115 is completely arbitrary!
See also
SYS_ExitWindows() , SYS_FatalExit()
SYS_ExitWindows() : Either logs off, shuts down, or shuts

down and restarts the system.
Alias
ExitWindows()
Syntax
SYS_ExitWindows( nMode )  lSuccess
Parameters
nMode shutdown operation.
Value Description
0 Logoff
1 Shuts down the system to a point at which it is safe to turn off the power. All file
buffers have been flushed to disk, and all running processes have stopped
2 Reboot
4 Forces processes to terminate. When this flag is set, Windows does not send the
messages WM_QUERYENDSESSION and WM_ENDSESSION to the applications
currently running in the system. This can cause the applications to lose data.
Therefore, you should only use this flag in an emergency
8 Shuts down the system and turns off the power. The system must support the
power-off feature
Returns
lSuccess .T. if the command could be executed; .F. if not.

System Functions
See also
SYS_FatalExit() , SYS_ExitProcess()
SYS_FatalExit() : Displays a message box and terminates the

application.
Comment
This function can be used if you detect a violation of the rights that are granted to a user.
Alias
FatalExit()
Syntax
SYS_FatalExit( szMsg )  you never return from this function
Parameters
szMsg message to be displayed in the dialog box. The dialog bow appears to be different in
Windows 95 and in Windows NT.
Returns
None.
Example
SYS_FatalExit( "Unexpected error. Quit" )
See also
SYS_ExitWindows() , SYS_ExitProcess()
SYS_FileSystemName() : File system installed on a given

drive.
Alias
FileSystemName(), FSName(),FileSystem();SYS_FileSystem()
Syntax
SYS_FileSystemName( szDrive )  szFS
Parameters
szDrive drive to consider. It contains the root directory of the volume whose file system is to be
determined. If this parameter is NULL , the root of the current directory is used. If this
parameter is a UNC name, you must follow it with an additional backslash. For example, you
would specify "\\MyServer\MyShare" as "\\MyServer\MyShare\" .
Returns
szFS file system ("FAT" , "NTFS" , "HPFS" , "CDFS" , etc.).
Example
IF ( SYS_FileSystemName( "C:\" ) == "NTFS" )
? "You can start using NTFS capabilities"
ENDIF

System Functions
SYS_FormatDrive() : Presents the standard dialog box of
Windows to format a drive.
Syntax
SYS_FormatDrive( nDrive )  .T.
Parameters
nDrive drive number (0=A, 1=B, 2=C, etc.)
Returns
Remark
Windows cannot format the drive on which its own files are located.
Example
SYS_FormatDrive( 3 )
See also
SYS_isMutex() , SYS_DeleteMutex()
SYS_FreeConsole() : Frees the current console (if any).

Syntax
SYS_FreeConsole()  lSuccess

System Functions
Parameters
None.
Returns
Example

ENDIF

SYS_FreeConsole()
SYS_FreeLibrary() : Unloads a 32-bit DLL previously loaded

with SYS_LoadLibrary().
Syntax
SYS_FreeLibrary( nInstanceHandle )  lSuccess
Parameters
nInstanceHandle handle of the DLL.
Returns
Example
LOCAL nInst
nInst = SYS_LoadLibrary( "MQM.DLL" )
IF ( nInst != -1 )
? "MQSeries server is installed"
ELSE
nInst = SYS_LoadLibrary( "MQIC32.DLL" )
IF ( nInst != -1 )
? "MQSeries client is installed"
ELSE
? "MQSeries is not installed"
ENDIF
ENDIF
IF ( nInst != -1 )
SYS_FreeLibrary( nInst )
ENDIF
SYS_GetBinaryType() : Determines the type of an executable.

Syntax
SYS_GetBinaryType()  nType

System Functions
Parameters
None.
Returns
nMilliSeconds the blink time, in milliseconds.
Value Description
0 Unknown
1 SCS_32BIT_BINARY
2 SCS_DOS_BINARY
3 SCS_OS216_BINARY
4 SCS_PIF_BINARY
5 SCS_POSIX_BINARY
6 SCS_WOW_BINARY
SYS_GetCaretBlinkTime() : Returns the elapsed time, in

milliseconds, required to invert the caret's pixels.
Alias
GetCaretBlinkTime()
Syntax
SYS_GetCaretBlinkTime()  nMilliSeconds
Parameters
None.
Returns
nMilliSeconds the blink time, in milliseconds.
Example
OldCaretBlinkTime = SYS_GetCaretBlinkTime()
See also
SYS_SetCaretBlinkTime()
SYS_GetCaretPosX() : Caret's position, in client coordinates.

Alias
GetCaretPosX()
Syntax
SYS_GetCaretPosX()  nPos
Parameters
None.

System Functions
Returns
nPos x-coordinate expressed in the current client coordinates.
See also
SYS_GetCaretPosY() , SYS_SetCaretPos()
SYS_GetCaretPosY() : Caret's position, in client coordinates.

Alias
GetCaretPosY()
Syntax
SYS_GetCaretPosY()  nPos
Parameters
None.
Returns
nPos y-coordinate expressed in the current client coordinates.
See also
SYS_GetCaretPosX() , SYS_SetCaretPos()
SYS_GetCommandLine() : Command-line string for the current

process.
Alias
GetCommandLine(), CommandLine()
Syntax
SYS_GetCommandLine()  cCmdLine
Parameters
None.
Returns
cCmdLine command line string used to start the current process.
SYS_GetCurrentDirectory() : Returns current directory.

Syntax
SYS_GetCurrentDirectory()  szDir
Parameters
None.

System Functions
Returns
szDir current directory. This function works on a remote computer where CURDIR() doesn't!
SYS_GetDllVersion() : Obtains version information from any

DLL.
Remark
This function uses the DllGetVersion() function of the DLL to query. This function is not an API function; it is
merely a convention that most DLLs follow. Note: FOCUS.FLL does not contain such a function so that it is impossible
to run SYS_GetDllversion() against FOCUS!
Syntax
SYS_GetDllVersion( szDLL,nInfo )  nVersionInfo
Parameters
szDLL the name of the DLL to query information from.
nInfo the member to obtain information for:
Value Description
1 Major number
2 Minor number
3 Build number
4 Platform ID
#define DLLVER_PLATFORM_WINDOWS 0x00000001 // Windows 95/98
#define DLLVER_PLATFORM_NT 0x00000002 // Windows NT
Any other Major number
numeric
value
Returns
nVersionInfo the version info that was queried. -1 if the DLL couldn't be opened. -2 if the version info
couldn't be obtained.
Example
? SYS_GetDllversion( "shell32.dll",1 ) // 4
See also
SHE_GetDllVersion()

System Functions
SYS_GetEnvironmentStrings() : Retrieves the whole
environment block of the current process.
See also
SYS_GetAllEnvironment() , SYS_GetWholeEnvironment() , SYS_GetEnvironmentVars()
Syntax
SYS_GetEnvironmentStrings( szVar )  szEnvironment
Parameters
None.
Returns
szEnvironment the value of the whole environment block. Each variable is separated by a caret ( ^).
Example
? SYS_GetEnvironmentStrings()
&& On our system it did return:
ALLUSERSPROFILE=C:\Documents and Settings\All UsersÂPPDATA=C:\Documents and Settings\Pat

Boens\Application
Data^classpath=D:\PROGRA~1\MQSeries\java\lib\COMIBM~2.JAR;D:\PROGRA~1\MQSeries\java\lib\COMIBM~1.JAR
;D:\PROGRA~1\MQSeries\java\lib\COMIBM~3.JAR;D:\PROGRA~1\MQSeries\tools\javaclnt\samples\en_us^Common
ProgramFiles=C:\Program Files\Common
Files^COMPUTERNAME=BETELGEUSE^ComSpec=C:\WINNT\system32\cmd.exe^CORPATH=C:\WINNT\Microsoft.NET\Frame
work\v1.0.2204\^HOMEDRIVE=C:^HOMEPATH=\ÎNCLUDE=D:\Program
Files\MQSeries\tools\cplus\include;D:\Program Files\MQSeries\tools\c\include^LIB=D:\Program
Files\MQSeries\tools\lib^LOGONSERVER=\\BETELGEUSE^NUMBER_OF_PROCESSORS=1ÔS=Windows_NTÔs2LibPath=C:
\WINNT\system32\os2\dll;^Path=C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;C:\Program
Files\Resource Pro Kit\;D:\Program Files\MQSeries\bin;D:\Program
Files\MQSeries\tools\c\samples\bin;C:\PROGRA~1\CRNADM~1;C:\MSSQL7\BINN;E:\ULTRAE~1^PATHEXT=.COM;.EXE
;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH^PROCESSOR_ARCHITECTURE=x86^PROCESSOR_IDENTIFIER=x86 Family 6
Model 8 Stepping 6, GenuineIntel^PROCESSOR_LEVEL=6^PROCESSOR_REVISION=0806^ProgramFiles=C:\Program
Files^SystemDrive=C:^SystemRoot=C:\WINNT^TEMP=C:\DOCUME~1\PATBOE~1\LOCALS~1\Temp^TMP=C:\DOCUME~1\PAT
BOE~1\LOCALS~1\TempÛSERDOMAIN=BETELGEUSEÛSERNAME=Pat BoensÛSERPROFILE=C:\Documents and
Settings\Pat Boens^windir=C:\WINNT
See also
SYS_SetEnvironmentVariable() , SYS_GetEnvironmentStrings()
SYS_GetEnvironmentVariable() : Retrieves the value of the

specified variable from the environment block of the
calling process.
Remark
The SYS_GetEnvironmentVariable() works better than the native GETENV() function of Visual FoxPro.
Syntax
SYS_GetEnvironmentVariable( szVar )  szValue
Parameters
szVar the variable to query

System Functions
Returns
szValue the value of the specified environment variable.
Example
IF ( SYS_SetEnvironmentVariable( "Hello World","This is Hello" ) )
? SYS_GetEnvironmentVariable( "Hello World" ) && "This is Hello"
? GETENV( "Hello World" ) && ""
ENDIF
See also
SYS_SetEnvironmentVariable() , SYS_GetEnvironmentStrings()
SYS_GetHInstance() : Retrieves the handle of the application

instance that handles the main FoxPro window.
Alias
GetHInstance()
Syntax
SYS_GetHInstance()  nInstance
Parameters
None.
Returns
nInstance application instance. If the function fails, the return value is set to zero.
See also
WIN_GetHInstance() .
SYS_GetLocalTime() : Gets the local time.

Alias
GetLocalTime()
Syntax
SYS_GetLocalTime()  szTime
Parameters
None.
Returns
szTime local time.
Example
? SYS_GetLocalTime() && "1997-11-16-0-23-41-59-880".

System Functions
SYS_GetNumDrives() : Finds out how many drives exist in the
system.
Alias
GetNumDrives(), GetDriveCount(), DriveCount()
Syntax
SYS_GetNumDrives()  nDrives
Parameters
None.
Returns
nDrives number of logical drives attached to the system.
SYS_GetStdHandle() : Gets the handle of a standard handle.

Syntax
SYS_GetStdHandle( nStdHandle )  nHandle
Parameters
nStdHandle the standard handle (standard input, standard output, standard error):
STD_INPUT_HANDLE -10
STD_OUTPUT_HANDLE -11
STD_ERROR_HANDLE -12
Returns
nHandle .T. handle if the function is successful; .F. if not. The handle can be used in subsequent calls
to FIL_Write() provided that FOCUS.FLL operates internally in the Win32 API mode instead
of the Fox mode (use FIL_SetOpenStrategy( 1 ) to set FOCUS.FLL in that mode).
Example
LOCAL nStdOutput
LOCAL nOldStrategy
m.nStdOutput = SYS_GetStdhandle( -11 )

&& If we were able to determine the STDOUT handle

IF ( m.nStdOutput != 0 )
&& Let's inform FOCUS that it has to deal with

&& The WIN32 API and not to operate in the
&& Fox mode!
m.nOldStrategy = FIL_SetOpenStrategy( 1 )
&& This will write to the standard output

FIL_Write( m.nStdOutput,"FIL_Write() does the job" + CHR(13) + CHR(10) )
&& This will close the standard output!

System Functions
&& FIL_close( m.nStdOutput )
&& Reset the strategy to what it was

FIL_SetOpenStrategy(m.nOldStrategy )
ENDIF
ENDIF
SYS_GetSysColor() : Retrieves the current color of the

specified display element.
Alias
GetSysColor()
Syntax
SYS_GetSysColor( nIndex )  nColor
Parameters
nIndex display element whose color is to be retrieved. This parameter must be one of the following
values:
Value Manifest Constant Description

21 COLOR_3DDKSHADOW Dark shadow for three-dimensional display
elements.
15 COLOR_3DFACE, Face color for three-dimensional display
COLOR_BTNFACE
elements.
20 COLOR_3DHILIGHT, Highlight color for three-dimensional display
COLOR_3DHIGHLIGHT,
COLOR_BTNHILIGHT, elements (for edges facing the light source.)
COLOR_BTNHIGHLIGHT
22 COLOR_3DLIGHT Light color for three-dimensional display
elements (for edges facing the light source.)
16 COLOR_3DSHADOW, Shadow color for three-dimensional display
COLOR_BTNSHADOW
elements (for edges facing away from the light
source).
10 COLOR_ACTIVEBORDER Active window border.
2 COLOR_ACTIVECAPTION Active window caption.
12 COLOR_APPWORKSPACE Background color of multiple document interface
(MDI) applications.
1 COLOR_BACKGROUND, Desktop.
COLOR_DESKTOP
18 COLOR_BTNTEXT Text on push buttons.
9 COLOR_CAPTIONTEXT Text in caption, size box, and scroll bar arrow
box.
17 COLOR_GRAYTEXT Grayed (disabled) text. This color is set to 0 if
the current display driver does not support a
solid gray color.
13 COLOR_HIGHLIGHT Item(s) selected in a control.
14 COLOR_HIGHLIGHTTEXT Text of item(s) selected in a control.
11 COLOR_INACTIVEBORDER Inactive window border.
3 COLOR_INACTIVECAPTION Inactive window caption.
19 COLOR_INACTIVECAPTIONTEXT Color of text in an inactive caption.
24 COLOR_INFOBK Background color for tool tip controls.
23 COLOR_INFOTEXT Text color for tool tip controls.
4 COLOR_MENU Menu background.
7 COLOR_MENUTEXT Text in menus.
0 COLOR_SCROLLBAR Scroll bar gray area.
5 COLOR_WINDOW Window background.
6 COLOR_WINDOWFRAME Window frame.
8 COLOR_WINDOWTEXT Text in windows.
Returns
nColor color of the display element.

System Functions
SYS_GetSystemMetrics() : Retrieves various system metrics
and system configuration settings.
Alias
GetSystemMetrics()
Remark
System metrics are the dimensions (widths and heights) of Windows display elements. All dimensions retrieved by
SYS_GetSystemMetrics() are in pixels.
Syntax
SYS_GetSystemMetrics( nIndex )  nValue
Parameters
nIndex specifies the system metric or configuration setting to retrieve. All SM_CX* values are widths.
All SM_CY* values are heights. The following values are defined:

SM_ARRANGE 56 Flags specifying how the system arranged minimized
windows.
SM_CLEANBOOT 67 Value that specifies how the system was started:
0 Normal boot
1 Fail-safe boot
2 Fail-safe with network boot
Fail-safe boot (also called SafeBoot) bypasses the user's
startup files.
SM_CMOUSEBUTTONS 43 Number of buttons on mouse, or zero if no mouse is
installed.
SM_CXBORDER, 5,6 The width and height, in pixels, of a window border. This is
SM_CYBORDER
equivalent to the SM_CXEDGE value for windows with the 3-D
look.
SM_CXCURSOR, 13,14 Width and height, in pixels, of a cursor. These are the
SM_CYCURSOR
cursor dimensions supported by the current display driver.
The system cannot create cursors of other sizes.
SM_CXDLGFRAME, 7,8 Same as SM_CXFIXEDFRAME and SM_CYFIXEDFRAME .
SM_CYDLGFRAME
SM_CXDOUBLECLK, 36,37 Width and height, in pixels, of the rectangle around the
SM_CYDOUBLECLK
location of a first click in a double-click sequence. The
second click must occur within this rectangle for the
system to consider the two clicks a double-click. (The two
clicks must also occur within a specified time.)
SM_CXDRAG, 68,69 Width and height, in pixels, of a rectangle centered on a
SM_CYDRAG
drag point to allow for limited movement of the mouse
pointer before a drag operation begins. This allows the
user to click and release the mouse button easily without
unintentionally starting a drag operation.
SM_CXEDGE, 45,46 Dimensions, in pixels, of a 3-D border. These are the 3-D
SM_CYEDGE
counterparts of SM_CXBORDER and SM_CYBORDER.
SM_CXFIXEDFRAME, Thickness, in pixels, of the frame around the perimeter of
SM_CYFIXEDFRAME
a window that has a caption but is not sizable.
SM_CXFIXEDFRAME is the width of the horizontal border and
SM_CYFIXEDFRAME is the height of the vertical border. Same as
SM_CXDLGFRAME and SM_CYDLGFRAME.
SM_CXFRAME, 32,33 Same as SM_CXSIZEFRAME and SM_CYSIZEFRAME.
SM_CYFRAME
SM_CXFULLSCREEN, 16,17 Width and height of the client area for a full-screen
SM_CYFULLSCREEN
window. To get the coordinates of the portion of the
screen not obscured by the tray, call the
GET_SystemParametersInfo() function with the SPI_GETWORKAREA
value.
SM_CXHSCROLL, ?,3 Width, in pixels, of the arrow bitmap on a horizontal scroll
SM_CYHSCROLL
bar; and height, in pixels, of a horizontal scroll bar.
SM_CXHTHUMB 10 Width, in pixels, of the thumb box in a horizontal scroll

System Functions
bar.
SM_CXICON, 11,12 The default width and height, in pixels, of an icon. These
SM_CYICON
values are typically 32x32, but can vary depending on the
installed display hardware. The LoadIcon() function can
only load icons of these dimensions.
SM_CXICONSPACING, 38,39 Dimensions, in pixels, of a grid cell for items in large icon
SM_CYICONSPACING
view. Each item fits into a rectangle of this size when
arranged. These values are always greater than or equal
to SM_CXICON and SM_CYICON.
SM_CXMAXIMIZED, 61,62 Default dimensions, in pixels, of a maximized top-level
SM_CYMAXIMIZED
window.
SM_CXMAXTRACK, 59,60 Default maximum dimensions, in pixels, of a window that
SM_CYMAXTRACK
has a caption and sizing borders. The user cannot drag the
window frame to a size larger than these dimensions. A
window can override these values by processing the
WM_GETMINMAXINFO message.
SM_CXMENUCHECK, 71,72 Dimensions, in pixels, of the default menu check-mark
SM_CYMENUCHECK
bitmap.
SM_CXMENUSIZE, 54,55 Dimensions, in pixels, of menu bar buttons, such as
SM_CYMENUSIZE
multiple document (MIDI) child close.
SM_CXMIN, 28,29 Minimum width and height, in pixels, of a window.
SM_CYMIN
SM_CXMINIMIZED, 57,58 Dimensions, in pixels, of a normal minimized window.
SM_CYMINIMIZED
SM_CXMINSPACING, 47,48 Dimensions, in pixels, of a grid cell for minimized windows.
SM_CYMINSPACING
Each minimized window fits into a rectangle this size when
arranged. These values are always greater than or equal
to SM_CXMINIMIZED and SM_CYMINIMIZED.
SM_CXMINTRACK, 34,35 Minimum tracking width and height, in pixels, of a window.
SM_CYMINTRACK
The user cannot drag the window frame to a size smaller
than these dimensions. A window can override these
values by processing the WM_GETMINMAXINFO message.
SM_CXSCREEN, 0,1 Width and height, in pixels, of the screen.
SM_CYSCREEN
SM_CXSIZE, Width and height, in pixels, of a button in a window's
SM_CYSIZE
caption or title bar.
SM_CXSIZEFRAME, 32,33 Thickness, in pixels, of the sizing border around the
SM_CYSIZEFRAME
perimeter of a window that can be resized. SM_CXSIZEFRAME is
the width of the horizontal border and SM_CYSIZEFRAME is the
height of the vertical border. Same as SM_CXFRAME and
SM_CYFRAME.
SM_CXSMICON, 49,50 Recommended dimensions, in pixels, of a small icon. Small
SM_CYSMICON
icons typically appear in window captions and in small icon
view.
SM_CXSMSIZE, 52,53 Dimensions, in pixels, of small caption buttons.
SM_CYSMSIZE
SM_CXVSCROLL, 2 Width, in pixels, of a vertical scroll bar; and height, in
SM_CYVSCROLL
pixels, of the arrow bitmap on a vertical scroll bar.
SM_CYCAPTION 4 Height, in pixels, of normal caption area.
SM_CYKANJIWINDOW 18 For double-byte character set versions of Windows, height,
in pixels, of the Kanji window at the bottom of the screen.
SM_CYMENU 15 Height, in pixels, of single-line menu bar.
SM_CYSMCAPTION 51 Height, in pixels, of a small caption.
SM_CYVTHUMB 9 Height , in pixels, of the thumb box in a vertical scroll bar.
SM_DBCSENABLED 42 TRUE or nonzero if the double-byte character set (DBCS)
version of USER.EXE is installed; FALSE , or zero
otherwise.
SM_DEBUG 22 TRUE or nonzero if the debugging version of USER.EXE is
installed; FALSE , or zero, otherwise.
SM_MENUDROPALIGNMEN 40 TRUE , or nonzero if drop-down menus are right-aligned
T
relative to the corresponding menu-bar item; FALSE , or
zero if they are left-aligned.
SM_MIDEASTENABLED 74 TRUE if the system is enabled for Hebrew/Arabic
languages.
SM_MOUSEPRESENT 19 TRUE or nonzero if a mouse is installed; FALSE , or zero,
otherwise.
SM_MOUSEWHEELPRESENT ? Windows NT only : TRUE or nonzero if a mouse with a
wheel is installed; FALSE , or zero, otherwise.
SM_NETWORK 63 The least significant bit is set if a network is present;

System Functions
otherwise, it is cleared. The other bits are reserved for
future use.
SM_PENWINDOWS 41 TRUE or nonzero if the Microsoft Windows for Pen
computing extensions are installed; zero, or FALSE ,
otherwise.
SM_SECURE 44 TRUE if security is present, FALSE otherwise.
SM_SHOWSOUNDS 70 TRUE or nonzero if the user requires an application to
present information visually in situations where it would
otherwise present the information only in audible form;
FALSE , or zero, otherwise.
SM_SLOWMACHINE 73 TRUE if the computer has a low-end (slow) processor,
FALSE otherwise.
SM_SWAPBUTTON 23 TRUE or nonzero if the meanings of the left and right
mouse buttons are swapped; FALSE , or zero, otherwise.
SM_CMETRICS 75 Number of indexes that are supported.
Returns
nValue If the function succeeds, the return value is the requested system metric or configuration
setting. If the function fails, the return value is zero.
SYS_GetThreadLocale() : Returns the calling thread's current

locale.
Alias
GetThreadLocale()
Syntax
SYS_GetThreadLocale()  nLocale
Parameters
None.
Returns
nLocale calling thread's 32-bit LCID locale identifier.
0x0401 1025 Arabic

0x0403 1027 Catalan
0x0405 1029 Czech
0x0406 1030 Danish
0x0407 1031 German
0x0408 1032 Greek
0x040B 1035 Finnish
0x040C 1036 French
0x040D 1037 Hebrew
System Functions
0x0410 1040 Italian
0x0412 1042 Korean
0x0413 1043 Dutch
0x0415 1045 Polish
0x0419 1049 Russian
0x041B 1051 Slovak
0x041D 1053 Swedish
0x041E 1054 Thai
0x041F 1055 Turkish
0x0420 1056 Urdu
0x0421 1057 Bahasa
Example
? SYS_GetThreadLocale()
SYS_GetTickCount() : Retrieves the number of milliseconds

that have elapsed since Windows was started.
Alias
GetTickCount()
Syntax
SYS_GetTickCount()  nMilliSeconds
Parameters
None.
Returns
nMilliSeconds number of milliseconds since Windows has started.
Example
? SYS_GetTickCount()
*-- You can also use SYS_GetTickCount() to form
*-- arbitrary names and numbers
SYS_GetTimeZoneInformation() : Retrieves the current time-

zone parameters
Alias
GetTimeZoneInformation() .

System Functions
Remark
The current time-zone parameters control the translations between Universal Time Coordinated (UTC) and local time.
All translations between UTC and local time are based on the following formula:
UTC = local time + bias
Syntax
SYS_GetTimeZoneInformation( nInfo )  xInfo
Parameters
nInfo type of desired information. Can be one of the following values :
Value Result Type of result

1 Bias numeric long
2 StandardName character string
3 StandardDate Not yet supported
4 StandardBias numeric long
5 DaylightName character string
6 DaylightDate Not yet supported
7 DaylightBias numeric long
The « Result » column refers to a member of a TIME_ZONE_INFORMATION structure. Here is

an explanation of each member :
Bias
Specifies the current bias, in minutes, for local time translation on this computer. The bias is the
difference, in minutes, between Coordinated Universal Time (UTC) and local time.
StandardName
Specifies a null-terminated string associated with standard time on this operating system. For
example, this parameter could contain "W" to indicate Western Standard Time. This string can
be empty.
StandardDate
This member is a structure (SYSTEMTIME ). That's the reason why it isn't yet supported
because that would oblige us to pass a second parameter to inform FOCUS what member of this
structure should be returned.
This structure contains a date and UTC when the transition from daylight time to standard time
occurs on the operating system.
Local time translations done during the standard-time range are relative to the StandardBias
value.
StandardBias
Specifies a bias value to be used during local time translations that occur during standard time.
This value is added to the value of the Bias member to form the bias used during standard
time. In most time zones, the value of this member is zero.
DaylightName
Specifies a null-terminated string associated with daylight time on this operating system. For
example, this parameter could contain "PDT" to indicate Pacific Daylight Time. This string can be
empty.

System Functions
DaylightDate
This member is also a structure (SYSTEMTIME ) (see remark above).
Local time translations during the daylight-time range are relative to the supplied
DaylightBias value. This member supports the absolute and day-in-month time formats of
the StandardDate member.
DaylightBias
Specifies a bias value to be used during local time translations that occur during daylight time.
This value is added to the value of the Bias member to form the bias used during daylight
time. In most time zones, the value of this member is -60.
Returns
xInfo see the above table to have an idea of the result of the function.
Examples
? SYS_GetTimeZoneInformation(1) && -60
? SYS_GetTimeZoneInformation(2) && "W"
? SYS_GetTimeZoneInformation(3) && "Standard Date is not yet supported"
? SYS_GetTimeZoneInformation(4) && 0
? SYS_GetTimeZoneInformation(5) && "W"
? SYS_GetTimeZoneInformation(6) && "Daylight Date is not yet supported"
? SYS_GetTimeZoneInformation(7) && -60
? SYS_GetTimeZoneInformation(8) && "Don't know what you want"
SYS_GetTmpPath() : Gets the Windows temporary path.

Alias
GetTmpPath(), GetTempPath()
Syntax
SYS_GetTmpPath()  szPath
Parameters
None.
Returns
szPath temporary path.
Example
? SYS_GetTmpPath() && "C:\WINDOWS\TEMP\"
SYS_GlobalMemoryStatus() : Retrieves information about

current available memory.
Comment
FOCUS provides the SYS_freerc() service to determine the available amount of resources. SYS_freerc() is
designed for FoxPro 2.6 only and has been superseded by SYS_GlobalMemoryStatus() .
Alias
GlobalMemoryStatus(), MemoryStatus()

System Functions
Syntax
SYS_GlobalMemoryStatus( [nSetting] )  nMemory
Parameters
nSetting type of requested information.
Value Return type

1 Memory Load. The return value gives a general idea of current memory utilization,
in which 0 indicates no memory use and 100 indicates full memory use.
2 Total Physical Memory. Indicates the number of bytes of physical memory
available.
3 Physical Memory Available. Indicates the number of bytes of physical memory
available.
4 Total Page File. Indicates the total number of bytes that can be stored in the
paging file. Note that this number does not represent the actual physical size of the
paging file on disk.
5 Available Page File. Indicates the number of bytes available in the paging file.
6 Total Virtual Memory. Indicates the total number of bytes that can be described in
the user mode portion of the virtual address space of the calling process.
7 Available Virtual Memory. Indicates the number of bytes of unreserved and
uncommitted memory in the user mode portion of the virtual address space of the
calling process.
Returns
nMemory amount of memory.
SYS_HideCaret() : Removes the caret from the screen.

Alias
HideCaret()
Syntax
SYS_HideCaret( [nHwnd] )  lSuccess
Parameters
nHwnd optional window handle. If not passed, the main FoxPro window is used.
Returns
lSuccess .T. is the function is successful; .F. otherwise.
See also
SYS_ShowCaret() .
SYS_inp() : input a byte from a port.

Caution
SYS_inp() and SYS_outp() cause illegal operations in Windows NT.
Syntax
SYS_inp( nPort )  nValue

System Functions
Parameters
nPort the port number.
Returns
nValue the value that is retrieved from the nPort port.
See also
SYS_outp() .
Example
? BITAND( SYS_inp( 0x379 ),16 ) == 16 && Pin 13 of LPT1 is set
SYS_iscd() : Is the given drive a CD-ROM?

Alias
SYS_IsDriveCD() .
Syntax
SYS_iscd( szDrive )  lCDROM
Parameters
szDrive root directory of drive to test.
Returns
lCDROM .T. if drive is a CD-ROM; .F. if not.
Example
IF ( SYS_iscd( "E:\" ) )
? "E is a CD-ROM."
ENDIF
See also
SYS_isremo() , SYS_isfixe() , SYS_isflop() , SYS_isram()
SYS_IsCompressed() : Determines if the specified volume is a

compressed volume.
Alias
IsCompressed()
Syntax
SYS_IsCompressed( szRootDir )  lCompressed
Parameters

System Functions
Returns
lCompressed .T. if compressed volume, .F. otherwise.
SYS_isDMA() : Is a DMA installed

Alias
IsDMA()
Syntax
SYS_isDMA()  lStatus
Parameters
None.
Returns
lStatus ????????.
SYS_IsDriveReady() : Is a given drive ready?

Alias
IsDrive(), IsDriveReady()
Syntax
SYS_IsDriveReady( szRootDir )  lReady
Parameters
If this parameter is a UNC name, you must follow it with a trailing backslash. For example, you
would specify \\MyServer\MyShare as \\MyServer\MyShare\ . However, a drive
specification such as "C:" cannot have a trailing backslash.
Windows 95: The initial release of Windows 95 did not support UNC paths for the szRootDir
parameter. To query the free disk space using a UNC path, temporarily map the UNC path to a
drive letter, query the free disk space on the drive, then remove the temporary mapping.
Windows 95 OSR2 and later: UNC paths are supported.
Returns
lReady .T. if drive is ready; .F. otherwise.
Example
DO WHILE ( .T. )
WAIT WINDOW "Please insert a formatted floppy in drive A: and press Enter"
IF ( SYS_IsDriveReady( "A:" ) )
EXIT
ENDIF
ENDDO

System Functions
SYS_IsFileCaseSensitive() : Does the system distinct between
upper and lower case filenames?
Comment
You can no longer rely on your former code for what concerns file handling (See File Functions Introduction to know
more about it). For example, on a case sensitive file system, the FILE( <szFile> ) test will return .T. or .F.
according to the case setting, which might be a nightmare to get rid of if you don't have a function to know if case is
of importance.
Alias
IsFileCaseSensitive()
Syntax
SYS_IsFileCaseSensitive( szRootDir )  lCaseSensitive
Parameters
Returns
lCaseSensitive .T. if system makes a difference between upper and lower case filenames; .F. otherwise.
Example
LOCAL lCaseSensitive
lCaseSensitive = SYS_IsFileCaseSensitive()
IF ( SYS_LastError() != 0 )
? "FOCUS was not able to access root directory"
ELSE
? IIF( lCaseSensitive , ;
"Case Sensitive File System" , ;
"File system is not case sensitive" ;
)
ENDIF
SYS_IsFileCasePreserved() : Does the system preserve cases?

Alias
IsFileCasePreserved()
Syntax
SYS_IsFileCasePreserved( szRootDir )  lCasePreserved
Parameters
Returns
lCasePreserved .T. if system makes preserves filename case; .F. otherwise.

System Functions
SYS_isfixe() : Is the given drive a fixed drive?
Alias
SYS_IsDriveFixed() .
Syntax
SYS_isfixe( szDrive )  lFixed
Parameters
Returns
lFixed .T. if drive is a fixed disk; .F. if not.
Example
IF ( ! SYS_isfixe( SYS_curdri() + ":\" ) )
? "This program requires a fixed disk"
ENDIF
See also
SYS_iscd() , SYS_isremo() , SYS_isflop() , SYS_isram()
SYS_IsFlop() : Is the given drive a floppy drive? (is disk

removable?)
Alias
SYS_IsDriveFloppy() , SYS_IsDriveRemovable() , SYS_IsFloppy() , IsDriveFloppy() ,
IsDriveRemovable() , IsRemovable() .
Syntax
SYS_IsFlop( szDrive )  lFloppy
Parameters
Returns
lFloppy .T. if disk can be removed from drive; .F. if not.
Example
IF ( SYS_IsFlop( "A:\" ) )
? "A is a floppy."
ENDIF
See also
SYS_IsCD() , SYS_isremo() , SYS_isfixe() , SYS_isram()

System Functions
SYS_IsGame() : Is a game adapter present?
Caution
This function does not work for the moment because the _bios_equiplist() is no longer available.
Alias
IsGame()
Syntax
SYS_IsGame()  lPresent
Parameters
None.
Returns
lPresent .T. if a game adapter is found; .F. if not.
SYS_IsLoaded() : Determines if a process (EXE) or library

(DLL) is loaded.
Syntax
SYS_IsLoaded( szWin32Module )  lLoaded
Parameters
szWin32Module name of a Win32 DLL or executable module. If the filename extension is omitted, the default
library extension .DLL is appended. The filename string can include a trailing point character (.)
to indicate that the module name has no extension. The string does not have to specify a path.
The name is compared (case independently) to the names of modules currently mapped into
the address space of the calling process.
Returns
lLoaded .T. if szWin32Module is loaded; .F. if not.
See also
SYS_ModuleHandle()
SYS_IsMath() : Is Math coprocessor present?

Caution
Alias
IsMath()
Syntax
SYS_IsMath()  lPresent

System Functions
Parameters
None.
Returns
lPresent .T. if a math coprocessor is found; .F. if not.
SYS_IsModem() : Is a modem present?

Caution
Alias
IsModem()
Syntax
SYS_IsModem()  lPresent
Parameters
None.
Returns
lPresent .T. if a modem is found; .F. if not.
SYS_IsMutex() : Does a given mutex object exist.

Remark
Alias
IsMutex()
Syntax
SYS_IsMutex( cMutex )  lExist
Parameters
cMutex string indicating the mutex name.
Returns
lExist .T. if the given mutex exists; .F. if not.
Example
&& This example checks whether a given mutex already exists;
&& if it exists, it measn that this application is in memory,
&& and consequently, already unloads
IF ( ! SYS_isMutex( "UniqueMutex" ) )
SYS_CreateMutex( "UniqueMutex" )
ELSE
QUIT
ENDIF

System Functions
See also
SYS_DeleteMutex() , SYS_CreateMutex()
SYS_isNT() : Is the application running under Windows NT?

Alias
IsNT()
Syntax
SYS_isNT()  lNT
Parameters
None.
Returns
lNT .T. if the application currently runs under Windows NT; .F. if not.
Example
LOCAL nMajor
LOCAL nMinor
LOCAL nBuild
nMajor = SYS_os(1)
nMinor = SYS_os(2)
nBuild = SYS_os(3)
IF ( SYS_isNT() )
DO CASE
CASE nMajor == 4 .AND nMinor == 0
? "Windows NT 4.0, Build",nBuild
CASE nMajor == 5 .AND nMinor == 0
? "Windows 2000, Build",nBuild
ENDCASE
ELSE
? "This application requires Windows NT."
ENDIF
SYS_ispen() : Is it a pen computing prepared machine?

Syntax
SYS_ispen()  lPenMachine
Parameters
None.
Returns
lPenMachine .T. if machine is pen prepared; .F. otherwise.
SYS_isram() : Is the given drive a RAM disk?

Alias
SYS_IsDriveRAMDisk() , IsDriveRAMDisk() , IsRAMDisk() , IsRAM()

System Functions
Syntax
SYS_isram( szDrive )  lRAMDisk
Parameters
Returns
lRAMDisk .T. if drive is a RAM disk; .F. if not.
Example
IF ( SYS_isram( "F:\" ) )
? "You are copying on a volatile disk"
ENDIF
See also
SYS_iscd() , SYS_isremo() , SYS_isfixe() , SYS_isflop()
SYS_isremo() : Is the given drive a remote drive?

Alias
SYS_IsDriveRemote() .
Syntax
SYS_isremo( szDrive )  lRemote
Parameters
Returns
lRemote .T. if drive is a remote drive; .F. if not. A remote drive is often a network drive.
Example
IF ( SYS_isremo( "J:\" ) )
? "J is a network drive."
ENDIF
See also
SYS_iscd() , SYS_isfixe() , SYS_isflop() , SYS_isram()
SYS_IsUnicodeOnDisk() : Does the file system support

Unicode in filenames as they appear on disk?
Syntax
SYS_IsUnicodeOnDisk( szDrive )  lUnicodePresent
Parameters

System Functions
Returns
lUnicodePresent .T. if Unicode on disk; .F. if not.
SYS_IsValidLocale() : Validity test to a locale identifier.

Syntax
SYS_IsValidLocale( nLocale,nTest )  lResult
Parameters
None.
Returns
nMilliSeconds number of milliseconds since Windows has started.
Example
? SYS_GetTickCount()
*-- You can also use SYS_GetTickCount() to form
*-- arbitrary names and numbers
SYS_JoyStickCaps() : Determines if the capabilities of a

joystick can be queried.
Syntax
SYS_JoyStickCaps( nJoy )  lSuccess
Parameters
nJoy identifier of the joystick to be queried.
Returns
lSuccess .T. if successful; .F. if not.
SYS_JoyStickEnumDevs() : Returns the number of joysticks

the joystick driver supports.
Syntax
SYS_JoyStickEnumDevs()  nJoys
Parameters
None.
Returns
nJoys number of joysticks.

System Functions
SYS_KillProcess() : Kills a given task.
Caution
This function does not work in NT 4.
Comment
SYS_Processes() and SYS_ProcessesId() are closely linked to each other in the sense that
SYS_ProcessesId() returns a string of process ids instead of a list of process names.
You can extract one of the process IDs in order to pass it to SYS_KillProcess() which is about to terminate the
task.
Syntax
SYS_KillProcesses( nID )  lSuccess
Parameters
nID process ID.
Returns
lSuccess .T. if the operation is successful; .F. if not.
Example
&& In this example, you can clearly see that we successively call
&& SYS_Processes() and SYS_ProcessesId(). These two function will
&& return the list of all the active tasks running on the system -
&& first the names, then the IDs.
&& In this example, WINWORD.EXE is loaded with the -93131 ID.
&& Finally, we can terminate WINWORD with a call to SYS_KillProcess() :
? SYS_Processes()
&& bit)^WINWORD.EXE(32-bit)^WINOLDAP(16-bit)^VFP.EXE(32-bit)
? SYS_ProcessesId()
&& -3178599^-47519^-18475^-31943^
&& -29199^-120175^-130915^-101511^
&& -106339^-108707^-82779^-86339^
&& -93131^-186587^-190975
? SYS_KillProcess( -93131 )
See also
SYS_Processes() , SYS_ProcessesId()
SYS_LastError() : Gets system functions last error.

Comment
Up to now, when some functions were unable to operate correctly, they simply position a flag indicating that an error
occurred. When this flag is set to 0, that means that no error occurred. Not all the system functions position the
internal flag.
Syntax
SYS_LastError()  nLastError

System Functions
Parameters
None.
Returns
nLastError 1 if the last system operation raised an error; 0 otherwise.
Example
LOCAL lCaseSensitive
lCaseSensitive = SYS_IsFileCaseSensitive()
IF ( SYS_LastError() != 0 )
? "FOCUS was not able to access root directory"
ELSE
? IIF( lCaseSensitive , ;
"Case Sensitive File System" , ;
"File system is not case sensitive" ;
)
ENDIF
SYS_LastVersion() : Returns the file stamp of SYS functions.

Remark
Syntax
SYS_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\SYS.C-Mon Oct 19 15:55:22 1998" .
SYS_LoadLibrary() : Attempts to load a 32-bit DLL.

Comment
You can use this function to determine whether a 32-bit DLL can be loaded in the conditions of the machine you're
facing. If you successfully load the given DLL that means you're facing certain conditions. For example, for a Visual
FoxPro program to interact with MQSeries (http://www.ibm.com/MQseries) it should know whether MQSeries Server or
Client is installed. This can be easily determined if we can load the MQM.DLL (Server) or the MQIC32.DLL (Client).
After the library has been successfully loaded, you have to unload it properly with SYS_FreeLibrary() .
Syntax
SYS_LoadLibrary( szDLL )  nInstanceHandle
Parameters
szDLL name of the DLL that must be loaded.

System Functions
Returns
nInstanceHandle handle of the DLL.
Example
LOCAL nInst
nInst = SYS_LoadLibrary( "MQM.DLL" )
IF ( nInst != -1 )
? "MQSeries server is installed"
ELSE
nInst = SYS_LoadLibrary( "MQIC32.DLL" )
IF ( nInst != -1 )
? "MQSeries client is installed"
ELSE
? "MQSeries is not installed"
ENDIF
ENDIF
IF ( nInst != -1 )
SYS_FreeLibrary( nInst )
ENDIF
SYS_LookupDomain() : Returns the first domain on which a

specified user is defined.
Caution
This function does not work in Win95 and Win98.
Syntax
SYS_LookupDomain( szUser )  szDomain
Parameters
cUser user name.
Returns
szDomain domain on which the given user is known. This function, although returning an empty string
(which is what can be expected), is useless with Win95, because there is no notion of a domain
with Win95.
SYS_MakeDrive() : From a number, it returns a drive letter.

Syntax
SYS_MakeDrive( nDrive )  szDrive
Parameters
nDrive drive number (1=A,2=B, etc.)
Returns
szDrive drive letter.

System Functions
SYS_MaxApplAddress() : Returns the highest memory address
accessible to applications and dynamic-link libraries
(DLLs).
Alias
MaxApplAddress()
Syntax
SYS_MaxApplAddress()  nAddress
Parameters
None.
Returns
nAddress highest memory address accessible to applications and dynamic-link libraries (DLLs).
SYS_MaxFileLength() : Obtains maximum filename length for a

given disk.
Alias
MaxFileLenth(), MaxComponentLength()
Syntax
SYS_MaxFileLength( szRootDir )  nLength
Parameters
Returns
nLength maximum filename length or -1 if function was unsuccessful.
Example
? SYS_MaxFileLength( "C:\" ) && 255
SYS_MediaType() : Determines the media type.

Caution
Under construction. Do not use at the moment.
Syntax
SYS_MediaType( szDrive )  nMediaType
Parameters
szDrive drive in which the media to be tested has been placed.

System Functions
Returns
nMediaType media type. <Place the forthcoming table here>
SYS_MinApplAddress() : Returns the lowest memory address

accessible to applications and dynamic-link libraries
(DLLs).
Alias
MinApplAddress()
Syntax
SYS_MinApplAddress()  nAddress
Parameters
None.
Returns
nAddress lowest memory address accessible to applications and dynamic-link libraries (DLLs).
SYS_MinimumDragHeight() : Minimum tracking height of a

window.
Alias
SCR_MinimumDragHeight()
Comment
The user cannot drag the windows frame to a size smaller than this dimension.
Syntax
SYS_MinimumDragHeight()  nPixels
Parameters
None.
Returns
SYS_MinimumDragWidth() : Minimum tracking width of a

window.
Alias
SCR_MinimumDragWidth()

System Functions
Comment
The user cannot drag the window’s frame to a size smaller than this dimension, in other terms, a form cannot be
resized to a smaller dimension than the return value of this function. However, the SYS_MinimumDragWidth()
takes the width of the sizable window frame in account: SYS_MinimumDragWidth() – ( 2 * SYSMETRIC(3) )
= Minimum form width.
Syntax
SYS_MinimumDragWidth()  nPixels
Parameters
None.
Returns
SYS_ModuleHandle() : Returns a module handle for a

specified module.
Alias
ModuleHandle()
Syntax
SYS_ModuleHandle( szWin32Module )  nModule
Internal Call
GetModuleHandle()
Parameters
szWin32Module name of a Win32 DLL or executable module. If the filename extension is omitted, the default
library extension .DLL is appended. The filename string can include a trailing point character (.)
to indicate that the module name has no extension. The string does not have to specify a path.
The name is compared (case independently) to the names of modules currently mapped into
the address space of the calling process.
If this parameter is an empty string ( ""), SYS_GetModuleHandle() returns a handle of the

file used to create the calling process.
Returns
nModule if the function succeeds, the return value is a handle to the specified module. If the function
fails, the return value is -1.
Special
The SYS_ModuleHandle() function returns a module handle for the specified module if the file has been mapped
into the address space of the calling process.
There is no guarantee that the module handle remains valid between the time this function returns the handle and the
time it is used by another function. For example, a thread might retrieve a module handle by calling
SYS_ModuleHandle() . Before the thread uses the handle in another function, a second thread could free the
module and the system could load another module, giving it the same handle as the module that was recently freed.
The first thread would then be left with a module handle that refers to a module different than the one intended.

System Functions
Example
See SYS_ModuleName() .
See also
SYS_ModuleName() , SYS_IsLoaded()
SYS_ModuleName() : Retrieves the full path and filename for

the executable file containing the specified module.
Alias
ModuleName()
Syntax
SYS_ModuleName( nModule )  szFileName
Internal Call
GetModuleFileName()
Parameters
nModule identifies the module whose executable filename is being requested.
Returns
szFileName filled in with the path and filename of the given module.
Example
* This example will request the module number of the
* FOCUS library loaded in the address space of the
* current process. Thereafter, the SYS_ModuleName()
* will retrieve the full path and filename
? SYS_ModuleName( SYS_ModuleHandle( "FOCUS.FLL" ))

&& yields something like ... "E:\BOOKS32\FOCUS.FLL".
* This second example will simply retrieve the full path and
* filename of the current process. This technique can
* successfully be applied to find out the executable file name
? SYS_ModuleName( SYS_ModuleHandle( "" ) )
See also
SYS_ModuleHandle()
SYS_mouse() : Returns the mouse driver which is used by

Windows.
Syntax
SYS_mouse()  szMouseDrv
Parameters
None.

System Functions
Returns
szMouseDrv mouse driver used by the system.
Example
? "Mouse driver : ",SYS_mouse()
SYS_networ() : Returns the network driver which is used by

Windows.
Syntax
SYS_networ()  szNetworkDrv
Parameters
None.
Returns
szNetworkDrv network driver used by the system.
Example
? "Network driver : ",SYS_networ()
SYS_numflo() : Floppy disk count.

Syntax
SYS_numflo()  nFloppies
Parameters
None.
Returns
nFloppies number of floppy disks installed.
SYS_numprn() : Number of printers.

Caution
This function does not work in Win95.
Syntax
SYS_numprn()  nPrns
Parameters
None.
Returns
nPrns number of printers installed.

System Functions
SYS_os() : Get OS infos.
Syntax
SYS_os( nSetting )  xInfo
Parameters
nSetting identifies the type of information the SYS_os() function must return.
Value Member Description

1 dwMajorVersio Identifies the major version number of the operating system.
n
2 dwMinorVersio Identifies the minor version number of the operating system.
n
3 dwBuildNumber Identifies the build number of the operating system.
4 dwPlatformId Identifies the platform supported by the operating system. This
member can have one of the following values:
VER_PLATFORM_WIN32s 0 Win32s on Windows 3.1
VER_PLATFORM_WIN32_WINDOWS 1 Win32 on Chicago
VER_PLATFORM_WIN32_NT 2 Windows NT
5 szCSDVersion Contains a zero-terminated string that provides arbitrary
additional information about the operating system such as
whether a Service pack has been installed.
Returns
xInfo when called, the SYS_os() function places OS information into a C structure. This information
includes major and minor version numbers, a build number, a platform identifier, and possibly
some descriptive text.
Example
IF ( SYS_os(1) == 4 .AND. SYS_os(2) == 0 .AND. ! SYS_IsNT() )
? "You are running under Windows 95"
ENDIF
szAdditional = SYS_os(5)
IF ( ! EMPTY( szAdditional ) )
? "Additional infor: " + szAdditional
ENDIF
SYS_OSLastError() : Returns an error string from the

Operating System about the last operation.
Syntax
SYS_OSLastError()  szErrorString
Parameters
None.
Returns
szErrorString a string about the last operation.

System Functions
SYS_outp() : output a byte to a port.
Caution
SYS_inp() and SYS_outp() cause illegal operations in Windows NT.
Syntax
SYS_outp( nPort,szValue|nValue )  .T.
Parameters
nPort the port number.
szValue|nValue numeric or character string (only the first char will be taken into account).
Returns
See also
SYS_inp() .
SYS_P3Serial() : Pentium III serial number.

Caution
This function does not work in NT4.
Syntax
SYS_P3Serial()  szSerial
Parameters
None.
Returns
szSerial Pentium III serial number or an empty string ( "") if the serial number cannot be determined
(use SYS_LastError() to obtain the details of the failure).
SYS_PageSize() : Specifies the page size and the granularity of

page protection and commitment.
Syntax
SYS_PageSize()  nSize
Parameters
None.
Returns
nSize page size used by the VirtualAlloc() function.

System Functions
SYS_Processes() : List of active tasks in the system
Comment
In Windows 95 the word “task” is not used anymore. We use the term “process” instead.
The SYS_tasks() function of FOCUS does differ from SYS_Processes() in the sense that it lists all applications
based on their window title whereas SYS_Processes() maps the loaded tasks into their EXE name.
Please notice that SYS_Processes() operates differently under Windows 9x and NT. In Windows 9x, the
function uses the ToolHelp32 functions that reside in the kernel32.dll whereas with NT it uses the
psapi.dll. This DLL isn't always distributed with Windows.
You can use the DLL Help Database of Microsoft. The DLL Help exists to assist developers, system administrators, and other
IT professionals who face file version conflicts with Microsoft software. Use DLL Help to identify which software installed a
specific version of a DLL (http://support.microsoft.com/servicedesks/fileversion/dllinfo.asp?sd=MSDN).
16-bit processes:
In Windows 9x, 32-bit processes and 16-bit processes are equal citizens … as far as ToolHelp32 is concerned. This is
far from being the case under Windows NT. Therefore, 16-bit processes aren't enumerated under Windows NT which
makes the nAppType parameter of the function useless: the parameter is simply ignored.
Alias
EnumProcesses()
Syntax
SYS_Processes( nAppTypes )  szList
Parameters
nAppTypes optional parameter: 0 by default. Can be 16 if you want to list 16-bit applications, or 32 for 32-
bit applications. This parameter is completely ignored when the function operates on the
Windows NT platform.
Returns
(^) like in this example :
"KERNEL32.DLL(32-bit)^MSGSRV32(16-bit)^MPREXE.EXE(32-bit)^VSHWIN32.EXE(32-
bit)^MMTASK(16-bit)ÊXPLORER.EXE(32-bit)^POINTEXE(16-bit)^SYSTRAY.EXE(32-
bit)^SAGE.EXE(32-bit)ÎNTERNAT.EXE(32-bit)^FINDFAST.EXE(32-bit)^SPOOL32.EXE(32-
bit)ÎNFOVIEW.EXE(32-bit)^MSVC.EXE(32-bit)^WINOLDAP(16-bit)^VFP.EXE(32-
bit)^CTCD(16-bit)^WINWORD.EXE(32-bit)"
When no parameter has been passed to the function, or when this parameter was 0, then each
process is clearly shown as a 32-bit or 16-bit process when run under Windows 9x. When run in
NT, the function does not add any process information (16-bit or 32-bit).
Example
? SYS_Processes() under Windows 95 or Windows 98 (Windows 9x)
&& bit)ÎNFOVIEW.EXE(32-bit)^MSVC.EXE(32-bit)^WINOLDAP(16-bit)^VFP.EXE(32-
&& bit)^CTCD(16-bit)^WINWORD.EXE(32-bit)

&& MSGSRV32^MMTASK^POINTEXE^WINOLDAP^CTCD

&& KERNEL32.DLL^MPREXE.EXE^VSHWIN32.EXEÊXPLORER.EXE^SYSTRAY.EXE^SAGE.EXE^
&& INTERNAT.EXE^FINDFAST.EXE^SPOOL32.EXEÎNFOVIEW.EXE^MSVC.EXE^VFP.EXE^WINWORD.EXE
? SYS_Processes() under Window NT (here Windows 2000 Professional)

smss.exe^winlogon.exe^services.exe^lsass.exe^svchost.exe^spoolsv.exe^svchost.exe^mdm.exeÂMQSVC.EXE^
navapsvc.exeâmqmsrvn.exe^npssvc.exe^jview.exe^regsvc.exe^MSTask.exe^WinMgmt.exeÊxplorer.EXEâmqzxm

System Functions
a0.exeâmqxssvn.exeâmqxssvn.exeâmqharmn.exeâmqhasmn.exeâtiptaxx.exe^POProxy.exe^Winampa.exeînte
rnat.exe^navapw32.exeÂcroTray.exeâmqmtbrn.exeâmqzllp0.exe^np.exeâmqrrmfa.exeâmqzlaa0.exeÂMQPCS
EA.EXE^RUNMQCHI.exeâmqxssvn.exe^RUNMQLSR.exeâmqzxma0.exeâmqxssvn.exeâmqxssvn.exeâmqhasmn.exeâm
qzllp0.exeâmqrrmfa.exeâmqzlaa0.exeÂMQPCSEA.EXE^RUNMQCHI.exe^RUNMQLSR.exeâlertsvc.exe^WINCMD32.EX
E^WINCMD32.EXE^psdk-
x86.exe^WebSetup.exe^msiexec.exe^msiexec.exeîmages2100.exe^WINCMD32.EXE^WINWORD.EXE^VFP6.EXE
See also
SYS_tasks(), SYS_EnumDeviceDrivers()
SYS_ProcessesId() : List of IDs of all active tasks

Caution
This function does not work in NT4.
Comment
SYS_Processes() and SYS_ProcessesId() are closely linked to each other in the sense that
SYS_ProcessesId() returns a string of process ids instead of a list of process names.
You can extract one of the process IDs in order to pass it to SYS_KillProcess() which is about to terminate the
task.
Please notice that SYS_ProcessesId() does not work under Windows NT.
Syntax
SYS_ProcessesId()  szList
Parameters
None.
Returns
szList list (IDs) of all active tasks running on the system. Each task is separated by each other by a
caret (^).
Example
&& In this example, you can clearly see that we successively call
&& SYS_Processes() and SYS_ProcessesId(). These two function will
&& return the list of all the active tasks running on the system -
&& first the names, then the IDs.
&& In this example, WINWORD.EXE is loaded with the -93131 ID.
&& Finally, we can terminate WINWORD with a call to SYS_KillProcess() :
? SYS_Processes()
&& bit)^WINWORD.EXE(32-bit)^WINOLDAP(16-bit)^VFP.EXE(32-bit)
? SYS_ProcessesId()
&& -3178599^-47519^-18475^-31943^
&& -29199^-120175^-130915^-101511^
&& -106339^-108707^-82779^-86339^
&& -93131^-186587^-190975
? SYS_KillProcess( -93131 )
See also
SYS_Processes() , SYS_KillProcess()

System Functions
SYS_ProcessorArchitecture() : Specifies the system's
processor architecture.
Syntax
SYS_ProcessorArchitecture()  szArchitecture
Parameters
None.
Returns
szArchitecture specifies the system's processor architecture. This value can be one of the following values:
Value Description
Intel PROCESSOR_ARCHITECTURE_INTEL
Mips PROCESSOR_ARCHITECTURE_MIPS
Alpha PROCESSOR_ARCHITECTURE_ALPHA
PowerPC PROCESSOR_ARCHITECTURE_PPC
Unknown PROCESSOR_ARCHITECTURE_UNKNOWN
SYS_ProcessorMask() : Returns a mask representing the set

of processors configured into the system.
Syntax
SYS_ProcessorMask()  nMask
Parameters
None.
Returns
nMask set of processors configured into the system. Bit 0 is processor 0; bit 31 is processor 31.
SYS_RealExecutableName() : Gets the name of the executable.

Alias
SYS_ExeNam(), SYS_ExeName(), RealExecutableName(), ExeName(), ExecutableName()
Syntax
SYS_RealExecutableName()  szName
Parameters
None.
Returns
szName Name of the running executable name.
Example
? SYS_RealExecutableName() && "D:\PROGRAM FILES\DEVSTUDIO\VFP\VFP.EXE"

System Functions
SYS_RemoteShutdown() : Initiates a shutdown and optional
restart of the specified computer.
Caution
This function is unsupported in Windows 95, Windows 98 and Windows Millennium. Only Administrators
can use this function needs SE_REMOTE_SHUTDOWN_NAME privilege on remote computers.
Alias
RemoteShutdown()
Syntax
SYS_RemoteShutdown( szComputer[,szMsg[,nTimeout[,lForce[,lReboot]]]])  lAccepted
Parameters
szComputer Network name of the computer to shut down.
szMsg Specifies a message to display in the shutdown dialog box
nTimeout Specifies the time (in seconds) that the shutdown dialog box should be displayed.
lForce Specifies whether applications with unsaved changes are to be forcibly closed. If this parameter
is TRUE, such applications are closed. If this parameter is FALSE, a dialog box is displayed
prompting the user to close the applications.
lReboot Specifies whether the computer is to restart immediately after shutting down. If this parameter
is TRUE, the computer is to restart. If this parameter is FALSE, the system flushes all caches to
disk, clears the screen, and displays a message indicating that it is safe to power down.
Returns
lAccepted .T. if the function is successful; .F. otherwise.
Example
? SYS_RemoteShutdown( "ORION","System shutdown in 60 seconds",60 )
SYS_secclu() : Gets the number of sectors per cluster on

given disk.
Caution
If you attempt to determine the number of sectors per cluster on a floppy, you need to be sure that a disk is inserted
in the drive, otherwise Windows will report a system error to Visual FoxPro which will cause a dialog box to be
displayed. You can prevent the dialog box from showing up with a call to SYS_errhan() .
Alias
SectorsPerCluster() .
Syntax
SYS_secclu( szDrive )  nSectors
Parameters
szDrive drive letter from which to obtain the number of sectors per cluster.

System Functions
Returns
nSectors number of sectors.
Example
LOCAL nClusters
LOCAL nSectors
LOCAL nBytes
LOCAL szDrive

&& Preventing a system error on a floppy

nOld = SYS_errhan(1)
? SYS_secclu( "A:\" )
SYS_errhan( nOld )
See also
SYS_totclu(), SYS_avaclu()
SYS_SendMessage() : Sends a specified message to a window

(or windows).
Remark
As opposed to the SYS_PostMessage() function, the SYS_SendMessage() function does not return until the
message has been processed.
Alias
SendMessage() .
Syntax
SYS_SendMessage( nHwnd,nMsg,nParam1,nParam2 )  nResult
Parameters
nHwnd window handle to which the message should be sent. If the same message has to be sent to
multiple windows, use the HWND_BROADCAST ( (HWND) 0xffff ) value.
nMsg message to send. Basically, all messages provided by Windows are supported by FOCUS.
Unfortunately, the list of such messages is so long that it could hardly fit in this documentation.
Report yourself to WM_* messages of the Win32 API. Here's a very short (very, very short) of
messages that can be used to send keystrokes to a window:
#define WM_KEYFIRST 0x0100

#define WM_KEYDOWN 0x0100
#define WM_KEYUP 0x0101
#define WM_CHAR 0x0102
#define WM_DEADCHAR 0x0103
#define WM_SYSKEYDOWN 0x0104
#define WM_SYSKEYUP 0x0105
#define WM_SYSCHAR 0x0106
#define WM_SYSDEADCHAR 0x0107
#define WM_KEYLAST 0x0108
System Functions
nParam1 first message parameter. Depends on nMsg .
nParam2 second message parameter. Depends on nMsg .
Returns
nResult the return value specifies the result of the message processing and depends on the message
sent.
See also
SYS_PostMessage(), SYS_PostThreadMessage()
SYS_SetCaretBlinkTime() : Sets the caret blink time to the

specified number of milliseconds.
Alias
SetCaretBlinkTime() .
Syntax
SYS_SetCaretBlinkTime( nMilliSeconds )  lSuccess
Parameters
nMilliSeconds specifies the new blink time, in milliseconds
Returns
lSuccess .T. if function was successful; .F. otherwise.
Example
? SYS_SetCaretBlinkTime( 200 )
See also
SYS_GetCaretBlinkTime()
SYS_SetCaretPos() : Sets caret's position, in client

coordinates.
Alias
SetCaretPos() .
Syntax
SYS_SetCaretPos( x,y )  lSuccess
Parameters
x horizontal position.
y vertical position.

System Functions
Returns
lSuccess If the function succeeds, the return value is .T. If the function fails, the return value is .F..
See also
SYS_GetCaretPosX() , SYS_SetCaretPos()
SYS_SetConsoleTitle() : Sets the title of the current console.

Syntax
SYS_SetConsoleTitle( szTitle )  lSuccess
Parameters
szTitle title of the console window.
Returns
Example
? SYS_GetConsoleTitle() && Should be "FOCUS Debugging Window"
SYS_SetConsoleTitle( "My new debugging window" )
ENDIF
SYS_setdri() : Sets current drive.

Syntax
SYS_setdri( szDrive )  .T.
Parameters
szDrive drive letter to test. It can be a full path with a drive specifier because the function will only pay
attention to the leftmost character.
Returns
.T. the function always returns a logical .T. . If you want to test the function result, you should
issue a SYS_curdri() call. If the drive you attempted to log onto and the current drive are
the same, it means that the call to SYS_setdri() was successful.
Example
SYS_setdri( "A" )
IF ( LEFT( SYS_curdri(),1 ) != "A" )
? "Attempt to log onto drive A failed"
ENDIF
SYS_SetEnvironmentVariable() : Sets the value of an

environment variable for the current process.
Syntax
SYS_SetEnvironmentVariable( szVar,szValue )  lSuccess

System Functions
Parameters
szVar the variable to query.
szValue the value of the specified environment variable. new value of the specified environment
variable. If this parameter is .NULL. , the variable is deleted from the current process’s
environment.
Returns
lSuccess .T. if the environment variable has been successfully added or set to the current process. .F.
if not.
Example
IF ( SYS_SetEnvironmentVariable( "Hello World","This is Hello" ) )
? SYS_GetEnvironmentVariable( "Hello World" ) && "This is Hello"
? GETENV( "Hello World" ) && ""
IF ( SYS_SetEnvironmentVariable( "Hello World",.NULL. ) )
? "The environment variable has been eliminated"
ENDIF
ENDIF
See also
SYS_GetEnvironmentVariable() .
SYS_SetErrorMode() : Controls whether the system will handle

the specified types of serious errors, or whether the
process will handle them.
Alias
SetErrorMode().
Syntax
SYS_SetErrorMode( nMode )  nPrevious
Parameters
nMode can be one of the following modes:
SEM_FAILCRITICALERRORS 0x0001 The system does not display the critical-

error-handler message box. Instead, the
system sends the error to the calling
process.
SEM_NOGPFAULTERRORBOX 0x0002 The system does not display the general-
protection-fault message box. This flag
should only be set by debugging
applications that handle general protection
(GP) faults themselves with an exception
handler.
SEM_NOALIGNMENTFAULTEXCEPT 0x0004 RISC only: The system automatically fixes
memory alignment faults and makes them
invisible to the application. It does this for
the calling process and any descendant
processes. This flag has no effect on x86
processors.
SEM_NOOPENFILEERRORBOX 0x8000 The system does not display a message
box when it fails to find a file. Instead, the
error is returned to the calling process.

System Functions
Returns
nPrevious previous state.
SYS_SetFileAPIsToANSI() : Causes a set of Win32 file

functions to use the ANSI character set code page.
Alias
SetFileAPIsToANSI() .
Syntax
SYS_SetFileAPIsToANSI()  .T.
Parameters
None.
Returns
See also
SYS_SetFileAPIsToOEM() .
SYS_SetFileAPIsToOEM() : Causes a set of Win32 file

functions to use the OEM character set code page.
Alias
SetFileAPIsToOEM() .
Syntax
SYS_SetFileAPIsToOEM()  .T.
Parameters
None.
Returns
See also
SYS_SetFileAPIsToANSI() .
SYS_SetLocalTime() : Gets the local time.

Alias
SetLocalTime() .

System Functions
Syntax
SYS_SetLocalTime( nYear,nMonth,nDay,nHour,nMinute,nSecond,nMilli )  lSuccess
Parameters
nYear hour.
nMonth month.
nDay day.
nHour hour.
nMinute minute.
nSecond second.
nMilli milliseconds.
Returns
SYS_setvol() : Sets a new volume label for a given disk.

Alias
SYS_SetVolumeLabel() , SYS_SetVolume() , SYS_SetLabel() , SYS_SetVol() , SetVolumeLabel() ,
SetVolume() , SYS_SetLabel()
Syntax
SYS_setvol( szRootDir,szVolume )  lSuccess
Parameters
szRootDir root directory of drive to change volume label.
szVolume new volume label. 11 characters maximum!
Returns
lSuccess .T. if function was successful; .F. otherwise.
Example
IF ( SYS_SetVolumeLabel( "C:\","PAT_C_586" ) )
? "Volume has been successfully changed to " + ;
SYS_volume( "C:\",1 ) && "PAT_C_586"
ENDIF
Caution
Do not use volume labels larger than 11 characters, because that generates General Protection Faults.
SYS_ShellAbout() : Displays a Shell About dialog box.

Alias
ShellAbout() .
Syntax
SYS_ShellAbout( cTitle,szAdditional )  .T.

System Functions
Parameters
cTitle string displayed in the title bar of the Shell About dialog box and on the first line of the dialog
box after the text "Microsoft Windows".
szAdditional text displayed in the dialog box after the version and copyright information.
Returns
Example
? SYS_ShellAbout( "VFP Word Magician","Author : Pat Y. Boens" )
SYS_ShellExecute() : Opens, explores or prints a specified file.

Remark
It is preferable to use the SYS_ShellExecuteEx() function that provides tighter control and that can avoid
applications responding to DDE conversations to generate illegal operations.
Alias
ShellExecute() .
Syntax
SYS_ShellExecute( szOperation,szFile,szParameters,szDir,nMode )  nError
Parameters
nHwnd window handle that will own the execution (in SYS_ShellExecute() , this parameter is
always assumed to be the main FoxPro window, which can cause some trouble if used with top-
level forms).
szOperation "open" , "explore" or "print" .
szFile file to open, to explore or to print. Please note that can open an executable file or a document
file. Shortcuts can also be mentioned.
szParameters if szFile is an executable, szParameters is a string that specifies parameters to be passed

to the application.
nMode specifies how the application window is to be shown.

System Functions
SW_HIDE 0 Hides the window and activates another window.
SW_MAXIMIZE 3 Maximizes the specified window.
SW_MINIMIZE 6 Minimizes the specified window and activates the next top-
level window in the Z order.
SW_RESTORE 9 Activates and displays the window. If the window is
minimized or maximized, Windows restores it to its original
size and position. An application should specify this flag
when restoring a minimized window.
SW_SHOW 5 Activates the window and displays it in its current size and
position.
SW_SHOWDEFAULT 10 Sets the show state based on the SW_ flag specified in the
STARTUPINFO structure passed to the
CreateProcess() function by the program that started
the application.
SW_SHOWMAXIMIZED 3 Activates the window and displays it as a maximized
window.
SW_SHOWMINIMIZED 2 Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE 7 Displays the window as a minimized window. The active
window remains active.
SW_SHOWNA 8 Displays the window in its current state. The active window
remains active.
SW_SHOWNOACTIVATE 4 Displays a window in its most recent size and position. The
active window remains active.
SW_SHOWNORMAL 1 Activates and displays a window. If the window is minimized
or maximized, Windows restores it to its original size and
position. An application should specify this flag when
displaying the window for the first time.
Returns
Example
? SYS_ShellExecute( "explore","C:\MY DOCUMENTS","","",5 )
? SYS_ShellExecute( "open" ,"C:\WINDOWS\DESKTOP\Power Management.doc","","",3 )
? SYS_ShellExecute( "explore","DESKTOP","","",5 )
See also
SYS_WinExec() , FIL_Explore()
SYS_ShellExecuteEx() : Opens, explores or prints a specified

file.
Alias
ShellExecuteEx() .
Parameters
SYS_ShellExecuteEx( nHwnd,szOperation,szFile,szParameters,szDir,nMode )  nError
Parameters
nHwnd window handle that will own the execution (in SYS_ShellExecute() , this parameter is
always assumed to be the main FoxPro window, which can cause some trouble if used with top-
level forms).
szOperation "open" , "explore" or "print" .

System Functions
szFile file to open, to explore or to print. Please note that can open an executable file or a document
file. Shortcuts can also be mentioned.
szParameters if szFile is an executable, szParameters is a string that specifies parameters to be passed

to the application.

position.
the application.
window.
remains active.
Returns
See also
SYS_WinExec() , FIL_Explore() , SYS_ShellExecuteEx() ,
SYS_ShowCaret() : Makes the caret visible on the screen at the

caret's current position.
Alias
ShowCaret()
Syntax
SYS_ShowCaret( [nHwnd] )  lSuccess

System Functions
Parameters
nHwnd optional window handle. If not passed, the main FoxPro window is used.
Returns
See also
SYS_HideCaret() .
SYS_sleep() : Suspends the execution of the current thread for

a specified interval.
Alias
SYS_pause(), Pause(), Sleep()
Syntax
SYS_sleep( nMilliSeconds )  .T.
Parameters
nMilliSeconds sleep time in milliseconds
Returns
Example
Try both examples to notice the difference:
* You should get the second window without being able

* to read the first
WAIT WINDOW "This program is not about to pause" NOWAIT
WAIT WINDOW "Before going on" NOWAIT
See the difference now !
WAIT WINDOW "This program is about to pause" NOWAIT

SYS_sleep( 3000 )
WAIT WINDOW "Before going on" NOWAIT
SYS_SplitTime() : Splits the current local time into its base

components.
Alias
SplitTime()
Syntax
SYS_SplitTime( @nYear,@nMonth,@nDay,@nHour,@nMinute,@nSecond,@nMilli )  .T.
Parameters
nYear year. Must be passed by reference.

System Functions
nMonth month. Must be passed by reference.
nDay day. Must be passed by reference.
nHour hours. Must be passed by reference.
nMinute minutes. Must be passed by reference.
nSecond seconds. Must be passed by reference.
nMilli milliseconds. Must be passed by reference.
Returns
Example
LOCAL nYear,nMonth ,nDay,
LOCAL nHour,nMinute,nSecond,nMilli
nYear = 0
nMonth = 0
nDay = 0
nHour = 0
nMinute = 0
nSecond = 0
nMilli = 0
SYS_SplitTime( @nYear,@nMonth,@nDay,@nHour,@nMinute,@nSecond,@nMilli )
SYS_StartService() : Starts a Windows NT Service.

Alias
StartService() .
Syntax
SYS_StartService( szMachine,szService )  lSuccess
Parameters
szMachine the machine on which szService must be started. If this parameter is .NULL., the local
machine is used.
szService the service that must be started on szMachine .
Returns
lSuccess .T. if the function was successful; .F. otherwise. Use The SYS_GetlastError() function to
know why the function has failed.
Example
LOCAL szAction,szServiceName
m.szAction = "START"
m.szServiceName = "My Web Server"
IF ( m.szAction == "START" )
&& Start the service now
IF ( SYS_StartService( .NULL.,m.szServiceName ) )
? "The service was started successfully"
ELSE

System Functions
? "The service could not be started", SYS_GetLastError()
ENDIF
ELSE
&& Stop the service now
IF ( SYS_StopService( .NULL.,m.szServiceName ) )
? "The service was stopped successfully"
ELSE
? "The service could not be stopped", SYS_GetLastError()
ENDIF
ENDIF
See also
SYS_StopService()
SYS_StopService() : Stops a Windows NT Service.

Alias
StopService() .
Syntax
SYS_StopService( szMachine,szService )  lSuccess
Parameters
szMachine the machine on which szService must be stopped. If this parameter is .NULL., the local
machine is used.
szService the service that must be stopped on szMachine .
Returns
lSuccess .T. if the function was successful; .F. otherwise. Use The SYS_GetlastError() function to
know why the function has failed.
Example
LOCAL szAction,szServiceName
m.szAction = "STOP"
m.szServiceName = "My Web Server"
IF ( m.szAction == "START" )
&& Start the service now
IF ( SYS_StartService( .NULL.,m.szServiceName ) )
? "The service was started successfully"
ELSE
? "The service could not be started", SYS_GetLastError()
ENDIF
ELSE
&& Stop the service now
IF ( SYS_StopService( .NULL.,m.szServiceName ) )
? "The service was stopped successfully"
ELSE
? "The service could not be stopped", SYS_GetLastError()
ENDIF
ENDIF
See also
SYS_StartService()

System Functions
SYS_swap() : Returns the name of the Windows swap file.
Syntax
SYS_swap()  szSwapFile
Parameters
None.
Returns
szSwapFile swap file used by the system.
Example
? "Swap file : ",SYS_swap()
SYS_sysdir() : Obtains the pathname of the Windows system

directory.
Alias
SysDir(), SystemDir(), SystemDirectory(), WindowsSystemDir(), WindowsSysDir(),
WindowsSystemDirectory()
Syntax
SYS_sysdir()  szWinSysDir
Parameters
None.
Returns
szWinSysDir path of the Windows startup directory. The pathname does not end with a backslash ( \), unless
the Windows system directory is in the root directory. The Windows System directory generally
contains the Windows libraries, drivers, font files, etc.
Example
? "Windows system directory : " + SYS_sysdir()
SYS_tasks() : List of active tasks in the system.

Comment
Windows 95 does talk about tasks anymore. This word has been replaced by a process whereas Windows 3.1 did use
one word or the other.
The SYS_tasks() function of FOCUS does differ from SYS_Processes() in the sense that it lists all applications
based on their window title whereas SYS_Processes() maps the loaded tasks into their EXE name.
Alias
Tasks()
Syntax
SYS_tasks( lTakeCurrent,lTakeInvisible)  szList

System Functions
Parameters
lTakeCurrent include current task in list? .T. = yes, .F. = no.
Optional parameter : .F. by default.
lTakeInvisible include invisible tasks in list? .T. = yes, .F. = no.
Optional parameter : .F. by default.
Returns
like in this example:
"^Microsoft Visual FoxPro^Microsoft Visual C++ - FOCUS.mak -

[SYS.C]^Microsoft Word - Focusnew^NC - NCMAIN^Windows API Quick
Reference^MS Developer Network^Program Manager"
Example
&& Assuming that the current window title is ...
&& Datasoft - Medical Manager
LOCAL szCurrentTitle
LOCAL szTasks
szCurrentTitle = UPPER( "Datasoft - Medical Manager" )

szTasks = UPPER( SYS_tasks() )
IF ( AT( szCurrentTitle,szTasks ) != 0 )
WAIT WINDOW "Current application already in memory." + ;
CHR(13) + "Quit immediately!"
ENDIF
See also
SYS_Processes()
SYS_totclu() : Gets the total number of clusters on given disk.

Alias
Clusters(), TotalClusters()
Syntax
SYS_totclu( szDrive )  nClusters
Parameters
szDrive drive letter form which to obtain the number of bytes per sector.
Returns
nClusters number of clusters on disk.
See also
SYS_avaclu()

System Functions
SYS_video() : Initial video mode.
Syntax
SYS_video()  nVideo
Parameters
None.
Returns
nVideo initial video mode.
Value Meaning
0 Reserved
1 40 x 25 color
2 80 x 25 color
3 80 x 25 monochrome
SYS_volume() : Obtains volume information for a given disk.

Alias
Volume()
Syntax
SYS_volume( szRootDir,nSetting )  xInfo
Parameters
nSetting determines which information to get.
Value Description
1 Volume name
2 Volume serial number
3 Maximum component length
(maximum filename length)
4 File system flags
5 File system name
Returns
xInfo requested information or .F. if function was unsuccessful.
Example
? SYS_volume( "C:\",1 ) && "PAT_C_586"
? SYS_volume( "C:\",2 ) && 123456789
? SYS_volume( "C:\",3 ) && 255
? SYS_volume( "C:\",4 ) && 457812
? SYS_volume( "C:\",5 ) && "FAT"

System Functions
SYS_VolumeName() : Obtains volume name for a given disk.
Alias
VolumeName()
Syntax
SYS_VolumeName( szRootDir )  szVolumeName
Parameters
Returns
szVolumeName volume name or empty string if function was unsuccessful.
Example
? SYS_VolumeName( "C:\" ) && "PAT_C_586"
SYS_VolumeSerial() : Obtains volume serial number for a

given disk.
Alias
VolumeSerial()
Syntax
SYS_VolumeSerial( szRootDir )  nSerial
Parameters
Returns
nSerial volume serial number or -1 if function was unsuccessful.
Example
? SYS_VolumeSerial( "C:\" ) && 47589456
SYS_winBuild() : Returns the build number of the operating

system.
Remarks
This function is identical to SYS_os(3) .
Syntax
SYS_winBuil()  nBuildNumber
Parameters
None.

System Functions
Returns
nBuildNumber operating system build number.
Example
* Under NT 4.0 for example
? "OS Build Number : " + LTRIM(STR(SYS_winBuild())) && "OS Build Number : 1381"
* Under Win95 for example

? "OS Build Number : " + LTRIM(STR(SYS_winBuild())) && "OS Build Number : 67109814"
SYS_windir() : Obtains the pathname of the Windows

directory.
Alias
SYS_WindowsDir(), WinDir(), WindowsDir(), WinDirectory(), WindowsDirectory()
Syntax
SYS_windir()  szDir
Parameters
None.
Returns
szDir path of the Windows startup directory. The pathname does not end with a backslash (\), unless
the Windows directory is in the root directory.
Example
? "Windows directory : " + SYS_windir()
SYS_WinExec() : Runs a specified application.

Alias
WinExec(), WinExecute(), Spawn()
Syntax
SYS_WinExec( szApplication[,nMode] )  lSuccess
Parameters
szApplication command line.

System Functions
position.
the application.
window.
remains active.
Returns
lSuccess .T. if application loaded successfully; .F. otherwise.
Example
&& Try to load MS-Word
? SYS_WinExec( "C:\MSOFFICE\WINWORD\WINWORD.EXE" )
&& Display a message on somebody else screen

? SYS_WinExec( "Net Send WALK2227 Are You Happy?" )
See also
SYS_ShellExecute()
SYS_WinExecEx() : Runs a specified process.

Remark
The SYS_WinExecEx() function of FOCUS.FLL is very close to SYS_WinExec() . However, both functions do the
same thing very differently. One visible change is that you can now get the Process Identifier (PID)
Syntax
SYS_WinExecEx( szApplication[,nMode] )  nPID
Parameters
szApplication command line.

System Functions
position.
the application.
window.
remains active.
Returns
nPID Process identifier or 0 if error.
Example
LOCAL nPID
m.nPID = SYS_WinExecEx( "D:\MYDIR\MYPROG.EXE arg1 arg2",SW_SHOWNORMAL )
<... you can have some code here>
&& I can decide to kill the process when no longer needed

SYS_KillProcess( m.nPID )
See also
SYS_ShellExecute(), SYS_WinExec()
SYS_winmaj() : Returns Windows major version number.

Alias
SYS_WindowsMajor(), WinMaj(), WindowsMaj(), WindowsMajor()
Syntax
SYS_winmaj()  nMajor
Parameters
None.
Returns
nMajor Windows major version number.

System Functions
Example
? "Win ver : " + LTRIM(STR(SYS_winmaj())) + "." + LTRIM(STR(SYS_winmin()))
SYS_winmin() : Returns Windows minor version number.

Alias
SYS_WindowsMinor(), WinMin(), WindowsMin(), WindowsMinor()
Syntax
SYS_winmin()  nMinor
Parameters
None.
Returns
nMinor Windows minor version number.
Example
? "Win ver : " + LTRIM( STR( SYS_winmaj() ) ) + "." + ;
LTRIM( STR( SYS_winmin() ) )
SYS_WriteConsole() : Writes a string to the current console.

Syntax
SYS_WriteConsole( szString )  lSuccess
Parameters
szString string to be written to current console.
Returns
Example

ENDIF

SYS_FreeConsole()

Time Functions
Time Functions

Time Functions
Functions Synopsis
Due to a lack of design when starting FOCUS, timer functions and time functions share the same function prefix :
TIM_*() . We apologize for this mess !
The Windows environment gives the developer a bunch of time oriented functions to work with. With few functions,
FOCUS sets major services at your disposal.
It's a marvelous opportunity for us to tell you that the Windows environment handles dates as times. It basically
means that working with times means working with dates.
In order to maintain the necessary consistency, times and dates are now all handled through their UTC (Universal Time
Coordinated) value. This makes it more convenient to distinguish the last update of a file, certainly when it comes to
compare time stamps of two files that are updated at two different places, Paris and Los Angeles for example.
So we come to this bottom line : dates and times are equivalent (time type, or DateTime type for Visual FoxPro), and
what's more all times are UTC values.
Therefore, we felt obliged to provide a lot of TIME functions whereas FoxPro only provides local time functions.
Please be aware that FOCUS time functions cannot operate on dates before 01-01-1970 !
Notice that all local times are determined by taking into account the daylight saving setting.
Section FoxPro FOCUS

Local Time UTC Local Time UTC
Time TIME() N/A TIM_localT( TIM_time() ) TIM_gmT( TIM_time() )
Date DATE() N/A TIM_localT( TIM_time() ) TIM_gmT( TIM_time() )
FoxPro
? DATE(), TIME()
Focus
nTime = TIM_time()
? TIM_date( nTime ), "Local time :" + TIM_localT( nTime ), ;
"UTC : " + TIM_gmT( nTime )

Time Functions
TIM_ctime() : Converts a time value retrieved via TIM_time() as

a character string.
Syntax
TIM_ctime( nTime )  szTime
Parameters
nTime current time with a number form.
Returns
szTime converted time.
Example
LOCAL nCurrentTime
nCurrentTime = TIM_time() && 807029258
? TIM_localt( nCurrentTime ) && "16:47:38"

? TIM_gmt( nCurrentTime ) && "14:47:38"
? TIM_ctime( nCurrentTime ) && "Sat Jul 29 16:47:38 1995"
TIM_FormatMilli() : Transforms a number of milliseconds in

HH:MM:SS.mmm.
Syntax
TIM_FormatMilli( nMilliSeconds )  szTimeString
Parameters
nMilliSeconds number of milliseconds to turn into a time string.
Returns
szTimeString converted time.
Example
? TIM_FormatMilli( 3600000 ) && "01:00:00.000"
? TIM_FormatMilli( 24 * 60 * 60 * 1000 ) && "24:00:00.000"
See also
TIM_FormatTimeInterval() .
TIM_FormatTimeInterval() : Converts a time interval, specified

in milliseconds, to a string.
Syntax
TIM_FormatTimeInterval( n )  szInterval
Parameters
n integer to treat as a time interval in milliseconds.

Time Functions
Returns
szInterval n expressed as a displayable time string.
Example
? TIM_FormatTimeInterval(400) && "0 sec"
? TIM_FormatTimeInterval(86400) && "1 min 26 sec"
? TIM_FormatTimeInterval(86400000) && "24 hr 0 sec"
? TIM_FormatTimeInterval(86460000) && "24 hr 1 min 0 sec"
See also
TIM_FormatMilli() .
TIM_GetNumberOfDays() : Computes the days difference

between two dates.
Syntax
TIM_GetNumberOfDays( dDate1,dDate2 )  nDays
Parameters
dDate1 first date to consider.
dDate2 second date to consider.
Returns
nDays the number of days between dDate1 and dDate2 .
Example
? TIM_GetNumberOfDays( DATE(),{18/11/59} ) && 13872
TIM_gmt() : Converts a time value retrieved via TIM_time() to

an Universal Time Coordinated (UTC).
Syntax
TIM_gmt( nTime )  szTime
Parameters
Returns
Example
LOCAL nCurrentTime


Time Functions
TIM_LastVersion() : Returns the file stamp of Time functions.
Remark
Syntax
TIM_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\FWTIME.C-Mon Oct 19 15:55:22 1998" .
TIM_localt() : Converts a time value retrieved via TIM_time() to

a local time string.
Syntax
TIM_localt( nTime )  szTime
Parameters
Returns
Example
LOCAL nCurrentTime

TIM_MakeSeconds() : Computes the number of seconds from

a time string.
Syntax
TIM_MakeSeconds( cTime )  nSeconds
Parameters
cTime first date to consider.

Time Functions
Returns
nSeconds the number of seconds expressed by cTime .
Example
? TIM_MakeSeconds( TIME() ) && 64972
TIM_MakeTime() : Computes a time value from a date.

Syntax
TIM_MakeTime( dDate,nSeconds )  nTime
Parameters
dDate date to transform to a time value.
nSeconds optional number of seconds to add to dDate .
Returns
nTime the number of seconds expressed by cTime .
Example
? TIM_MakeTime( DATE(),TIM_MakeSeconds( TIME() ) ) && 879189312
? TIM_time() && Identical !!!
TIM_SetFormat() : Customizes the internal string buffer that

TIM_UserTime() will use.
Comment
The TIM_SetFormat() and TIM_UserTime() are closely related to each other. The TIM_UserTime() permits to
obtain a string which is capable to express a DateTime value into any suitable form. For example, given a date, it is
possible to have the following returns from TIM_UserTime() : "Today is Tue" or "Today is Tuesday 08
August (08/08/95)" or even "Today is Tuesday 08 August (08/08/95). This date is day 220
of the year" . In fact, any form fits. It's just up the developer to mention how he wants to get the result.
By default, the internal setting is set to "%d-%m-%Y at %H:%M:%S" .
In order for TIM_UserTime() to return an appropriate format, you can should use the TIM_SetFormat() function.
Syntax
TIM_SetFormat( szFormat )  szCurFormat
Parameters
szFormat time format string. By default, the internal setting is set to "%d-%m-%Y at %H:%M:%S" .

Time Functions
Escape Description
%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%c Date and time representation appropriate for locale
%d Day of month as decimal number (01 - 31)
%H Hour in 24-hour format (00 - 23)
%I Hour in 12-hour format (01 - 12)
%j Day of year as decimal number (001 - 366)
%m Month as decimal number (01 - 12)
%M Minute as decimal number (00 - 59)
%p Current locale's A.M./P.M. indicator for 12-hour clock
%S Second as decimal number (00 - 59)
%U Week of year as decimal number, with Sunday as first day of week (00
- 51)
%w Weekday as decimal number (0 - 6; Sunday is 0)
%W Week of year as decimal number, with Monday as first day of week (00
- 51)
%x Date representation for current locale
%X Time representation for current locale
%y Year without century, as decimal number (00 - 99)
%Y Year with century, as decimal number
Returns
szCurFormat the function returns the previous setting.
Example
LOCAL nTime
nTime = TIM_time() && Let's FOCUS handle the current time
TIM_SetFormat( "Today is %a" )

? TIM_UserTime( nTime ) && "Today is Tue"
TIM_SetFormat( "Today is %A" )

? TIM_UserTime( nTime ) && "Today is Tuesday"
TIM_SetFormat( "Today is %A %d %B" )

? TIM_UserTime( nTime ) && "Today is Tuesday 08 August"
TIM_SetFormat( "Today is %A %d %B (%x)" )

? TIM_UserTime( nTime ) && "Today is Tuesday 08 August
&& (08/08/95)"
? TIM_SetFormat("%Y-%m-%dT%H:%M:%S") && Used to turn a UTC time into a datetime

? CTOT(TIM_UserTime( nTime )) && "29/11/2002 17:36:15" (French date setting)
TIM_SetSystemTime() : Sets the system time to an Universal

Coordinated Time (UTC).
Syntax
TIM_SetSystemTime( UCTime )  lSuccess
Parameters
UCTime universal coordinated time string.
Returns
lSuccess .T. if operation is successful; .F. otherwise.

Time Functions
The application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this
function to succeed. This privilege is disabled by default. Use the
AdjustTokenPrivileges() function to enable the privilege and again to disable it after the
time has been set.
Example
* This example won't change anything as far as the system time
* is concerned. This is due to the fact that it sets the system
* time at what it was. However, you have the basic principles
* that must be used to control these settings.
LOCAL nUCTime
LOCAL cUCTime
nUCTime = TIM_time()
cUCTime = TIM_gmt( nUCTime )
? TIM_SetSystemTime( cUCTime )
TIM_SplitMilli() : Splits a number of millseconds into its basic

components (HH:MM:SS.mmm).
Syntax
TIM_SplitMilli( nMilliSeconds,@nHH,@nMM,@nSS,@nm )  szTimeString
Parameters
nMilliSeconds number of milliseconds to split.
nHH number to receive the hours. Must be passed by reference.
nMM number to receive the minutes. Must be passed by reference.
nSS number to receive the seconds. Must be passed by reference.
nm number to receive the milliseconds. Must be passed by reference.
Returns
szTimeString converted time.
Example
LOCAL nHH,nMM,nSS,nm
nHH = 0
nMM = 0
nSS = 0
nm = 0
? TIM_SplitMilli( 3600000,@nHH,@nMM,@nSS,@nm ) && "01:00:00.000"
? nHH && 1
? nMM && 0
? nSS && 0
? nm && 0
TIM_ticks() : Returns the number of milliseconds since

Windows was started.
Syntax
TIM_ticks()  nTicks

Time Functions
Parameters
None.
Returns
nTicks number of milliseconds elapsed since Windows was started.
TIM_time() : Gets the current time.

Syntax
TIM_time()  nTime
Parameters
None.
Returns
Example
See TIM_localt(), TIM_gmt(), TIM_ctime().
TIM_UserTime() : Gets a formatted string expressing a

DateTime value.
Comment
The TIM_SetFormat() and TIM_UserTime() are closely related to each other. The TIM_UserTime() permits to
obtain a string which is capable to express a DateTime value into any suitable form. For example, given a date, it is
possible to have the following returns from TIM_UserTime() : "Today is Tue" or "Today is Tuesday 08
August (08/08/95)" or even "Today is Tuesday 08 August (08/08/95). This date is day 220
of the year" . In fact, any form fits. It's just up the developer to mention how he wants to get the result.
In order for TIM_UserTime() to return an appropriate format, you can should use the TIM_SetFormat() function.
Syntax
TIM_UserTime( tTime )  szTime
Parameters
tTime a time value like the one returned by TIM_time() .
Returns
szTime resulting string compliant to TIM_SetFormat() setting.
Example
LOCAL nTime
nTime = TIM_time() && Let's FOCUS handle the current time
TIM_SetFormat( "Today is %a" )

? TIM_UserTime( nTime ) && "Today is Tue"
TIM_SetFormat( "Today is %A" )

? TIM_UserTime( nTime ) && "Today is Tuesday"

Time Functions
TIM_SetFormat( "Today is %A %d %B" )
? TIM_UserTime( nTime ) && "Today is Tuesday 08 August"
TIM_SetFormat( "Today is %A %d %B (%x)" )

? TIM_UserTime( nTime ) && "Today is Tuesday 08 August
&& (08/08/95)"
? TIM_SetFormat("%Y-%m-%dT%H:%M:%S") && Used to turn a UTC time into a datetime

? CTOT(TIM_UserTime( nTime )) && "29/11/2002 17:36:15" (French date setting)

Timer Functions
Timer Functions

Timer Functions
Functions Synopsis
Timer functions can definitely help you designing procedures that will be interrupted at a regular time interval.
Examples of such timer functions are numerous: alarms, CD front panel update, stopwatch, etc. These functions were
existing in FOCUS.FLL for FoxPro 2.5 already. They are provided for backward compatibility because, with the advent
of Visual FoxPro 3.0, the developer has now native timers at his disposal.
Timers
The use of timers implies 3 basic steps:
1. to tell FOCUS which command to launch at given time interval (TIM_proc() )
2. to set the global timer (TIM_set() )
3. to kill the timer (TIM_kill() )
Unlike other libraries, with FOCUS.FLL you can customize the command that must be executed at a regular time
interval. This command can be any valid FoxPro statement such as DO MYPROC , @ 10,10 SAY TIME() , etc.
TIM_proc() provides this service to you.
After you told FOCUS.FLL the command to be executed, you should specify the time interval you want to set. For this
purpose, use the TIM_set( TimeInterval ) function. It will return a timer identifier, which you’ll have to use to
kill the given timer when you want to stop it.
When you definitely want to change the timer or if you simply want to stop it, please use the TIM_kill() function
and pass it the timer identifier that was returned by TIM_set() .
Make sure when you quit your FoxPro application to kill the timer otherwise you may hang up the computer.
Limitations
So far, FOCUS accepts to position only 1 timer at a time. For this reason, we call it the global application timer. In the
future, more timers will be available.
Example
Coming up is an example of a routine that sets the global timer to a command whose aim is to display a clock during
GET editing.
SET LIBRARY TO FOCUS && Enable FOCUS functions

PUBLIC gtTimer
PRIVATE szVar
szVar = SPACE(11) && Prepare variable
TIM_proc( "WAIT WINDOW (TIME(1))" ) && Tailor timer command

gtTimer = TIM_set( 1000 ) && Time interval set at 1s
&& tTimer = timer identifier
@ 1,1 GET szVar DEFAULT "Hello World"
READ
TIM_kill( gtTimer ) && Kill timer
SET LIBRARY TO && Disable FOCUS functions

Obsolete
TIM_set() , TIM_kill() and TIM_proc() are obsolete. They have been superseded by the TMR_create() and
TMR_destroy() which provide higher precision and which can be used to create multiple timers instead of a unique
global timer.
High Precision Timers
High Precision timers are timers used in multimedia timers, where, for example, there are needed for MIDI sequencing
and so on. High Precision timers are needed to really interrupt Visual FoxPro while it is currently executing a command
such as REINDEX , PACK , etc. These commands, when operating on large tables, can take a while before completion.
High Precision timers can therefore be used to display a progress bar.

Timer Functions
TIM_kill() : Kills the global timer.

Remark
This function is obsolete. It is provided for backward compatibility.
Syntax
TIM_kill( tTimer )  .T.
Parameters
tTimer timer identifier. This identifier identifies the timer that must be killed.
Returns
Example
LOCAL tTimer
TIM_proc( "WAIT WINDOW (TIME()) NOWAIT" )
tTimer = TIM_set( 1000 )
<more instructions>
TIM_kill( tTimer )
TIM_proc() : Customizes the command to be executed by the

global timer.
Remark
This function is obsolete because Visual FoxPro has now timers (it wasn't the case in FoxPro 2.5!). It is provided for
backward compatibility.
Syntax
TIM_proc( szCommand )  .T.
Parameters
szCommand FoxPro command.
Returns
Example
LOCAL tTimer
<more instructions>
TIM_kill( tTimer )

Timer Functions
TIM_set() : Sets the global timer.
Remark
This function is obsolete. It is provided for backward compatibility.
Syntax
TIM_set( nMilliSeconds )  tTimer
Parameters
nMilliSeconds time interval in milliseconds.
Returns
tTimer the function returns the timer identifier.
Example
LOCAL tTimer
<more instructions>
TIM_kill( tTimer )
TMR_Create() : Creates a timer.

Caution
Don't create timers with "High Precision" yet. These timers create illegal operations. Although they're
supposed to be the most accurate timers and they're supposed to really interrupt Visual FoxPro in what it
currently does, these timers should still be fine-tuned. In fact, High Precision timers created with the
timeSetEvent() function are running in a separate thread and separate threads always proved to be a
problem with Visual FoxPro. Stay tuned.
Syntax
TMR_Create( nMilliSeconds,szCommand[,xHighPrecision] )  nHandle
Parameters
nMilliSeconds time interval in milliseconds.
szCommand command to be executed by the timer.
xHighPrecision this parameter is optional. If passed, the function creates a "High Precision" timer; if not
passed, the function creates a "Normal Precision" timer.
Returns
nHandle handle to a timer, or –1 if no timer could be created.
Example
&& This example will create a timer that will display the current time
&& while waiting for a key during 10 seconds.
LOCAL nHandle
nHandle = TMR_Create( 500,"WAIT WINDOW (TIME(1)) NOWAIT" )

Timer Functions
INKEY( 10,"HM" )
TMR_Destroy( nHandle )
TMR_Destroy() : Destroys a timer.

Caution
Each timer HAS to be destroyed before releasing FOCUS.FLL .
Syntax
TMR_Destroys( nHandle )  lSuccess
Parameters
nHandle handle of the timer to destroy.
Returns
lSuccess .T. if the timer was successfully destroyed; .F. if not.
Example
&& This example will create a timer that will display the current time
&& while waiting for a key during 10 seconds.
LOCAL nHandle
INKEY( 10,"HM" )
TMR_Destroy( nHandle )
TMR_HandlesCount() : Returns the maximum number of

handles.
Syntax
TMR_HandlesCount()  nHandles
Parameters
None.
Returns
nHandles maximum umber of timer handles.
TMR_HandlesFree() : Returns the number of free timer

handles.
Syntax
TMR_HandlesFree()  nHandles
Parameters
None.

Timer Functions
Returns
nHandles number of free handles.
TMR_info() : Returns timer information.

Syntax
TMR_Info( nHandle,nType )  xInfo
Parameters
nHandle handle identifying the timer to be queried. Be careful to pass a handle whose value is comprised
between TMR_MinHandle() and TMR_MaxHandle() ; otherwise illegal operations can
appear.
nType information type to query.
VALUE DESCRIPTION
1 Command associated with the timer. Return type: character string.
2 Internal timer identifier. Return type: numeric.
3 Timer interval. Return type: numeric.
4 Timer precision: 0 for NORMAL_PRECISION, 1 for HIGH_PRECISION. Return type:
numeric.
5 Timer suspended or not; .T. if timer is suspended, .F. if not. Return type:
logical.
Returns
xInfo the info as it is queried, depending on the nType parameter.
nType DESCRIPTION
1 Command associated with the timer. Return type: character string.
2 Internal timer identifier. Return type: numeric.
3 Timer interval. Return type: numeric.
4 Timer precision: 0 for NORMAL_PRECISION, 1 for HIGH_PRECISION. Return type:
numeric.
5 Timer suspended or not; .T. if timer is suspended, .F. if not. Return type:
logical.
Example
LOCAL nHandle
nHandle = TMR_create( 1000,"WAIT WINDOW (TIME()) NOWAIT" )

? TMR_info( nHandle,1 ) && "WAIT WINDOW (TIME()) NOWAIT"
? TMR_info( nHandle,2 ) && 572 (Internal identifier – never used)
? TMR_info( nHandle,3 ) && 1000 (Internal in milliseconds)
? TMR_info( nHandle,4 ) && 0 (Normal precision as opposed to 1 for high precision)
? TMR_info( nHandle,5 ) && .F. (Timer is not suspended)
TMR_LastError() : Returns an error string indicating the nature

of the last error encountered.
Syntax
TMR_LastError()  szError

Timer Functions
Parameters
None.
Returns
szError last error string.
TMR_LastVersion() : Returns the file stamp of TMR functions.

Remark
Syntax
TMR_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\TIMER.C-Mon Oct 19 15:55:22 1998" .
TMR_MaxHandle() : Returns the highest possible handle.

Syntax
TMR_MaxHandle()  nHandle
Parameters
None.
Returns
nHandle highest potential handle.
TMR_MinHandle() : Returns the lowest possible handle.

Syntax
TMR_MinHandle()  nHandle
Parameters
None.
Returns
nHandle lowest potential handle.

Timer Functions
TMR_Resume() : Resumes a timer.
Syntax
TMR_Resume( nHandle )  lSuccess
Parameters
nHandle handle identifying the timer to be resumed. Be careful to pass a handle whose value is
comprised between TMR_MinHandle() and TMR_MaxHandle() ; otherwise illegal operations
can appear.
Returns
lSuccess .T. if the timer is successfully resumed; .F. if not.
Example
LOCAL nHandle
INKEY( 20,"HM" ) && Let the timer be active for 20 seconds
TMR_Suspend( nHandle ) && Suspend the timer now
INKEY( 10,"HM" ) && Let the timer be suspended for 10 seconds
TMR_Resume( nHandle ) && Resume it now
ENDIF
TMR_Suspend() : Suspends a timer.

Syntax
TMR_Suspend( nHandle )  lSuccess
Parameters
nHandle handle identifying the timer to be suspended. Be careful to pass a handle whose value is
comprised between TMR_MinHandle() and TMR_MaxHandle() ; otherwise illegal operations
can appear.
Returns
lSuccess .T. if the timer is successfully suspended; .F. if not.
Example
LOCAL nHandle
INKEY( 20,"HM" ) && Let the timer be active for 20 seconds
TMR_Suspend( nHandle ) && Suspend the timer now
INKEY( 10,"HM" ) && Let the timer be suspended for 10 seconds
TMR_Resume( nHandle ) && Resume it now
ENDIF

Tracing Functions
Application Tracing Oriented Functions

Tracing Functions
Functions Synopsis
Application tracing functions are especially helpful at the debugging stage of an application. It provides easy methods
to set up a new tracing file, to log strings to the tracing log file, and to stop and start tracing the program on the fly.
When mixed with DDA techniques, you easily trace all program activity thanks to TRA_*() functions.
In version 5.17 of FOCUS.FLL , these functions, although totally operational, are in a kind of review process.
Internally, up to now, these functions were using their own code. In the future, they will use the common code of the
LOG_*() functions. So will the DDA_*() functions that report their activity in log files.
In the future you will see more Tracing functions also.

Tracing Functions
TRA_getlog() : Retrieves the name of the tracing log file.

Alias
TRA_GetTracingFile()
Syntax
TRA_getlog()  szTracingLogFile
Parameters
None.
Returns
szTracingLogFile name of the file tracing process is directed to.
Example
TRA_setlog( "" )
? TRA_getlog() && ""
TRA_setlog( "TRACING.LOG" )
? TRA_getlog() && "TRACING.LOG"
TRA_LastVersion() : Returns the file stamp of TRA functions.

Remark
Syntax
TRA_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\TRACING.C-Mon Oct 19 15:55:22 1998" .
TRA_log() : Logs a string in the tracing log file.

Syntax
TRA_log( szString )  .T.
Parameters
szString string to write to tracing log file
Returns

Tracing Functions
Example
TRA_log( "This string will be logged" )
TRA_setlog() : Sets the name of the tracing log file.

Alias
TRA_SetTracingFile()
Syntax
TRA_setlog( szLogFile )  lSuccess
Parameters
szLogFile application tracing file name.
Returns
Example
TRA_setlog( "" )
? TRA_getlog() && ""
? TRA_getlog() && "TRACING.LOG"

Version Functions
Version

Version Functions
Functions Synopsis
Application version functions are designed to control features that are somehow related to the version of the
application (author name, application name, application major version number, application minor version number, beta
flag, alpha flag, application INI file, and application date, company name, copyrights, etc.).
The entire information is held in a C structure:
#define VER_BUFFER_SIZE 257
typedef struct {
int VerMajor;
int VerMinor;
TCHAR Revision[11];
int Counter;
BOOL Alpha;
BOOL Beta;
BOOL PreRelease;
BOOL Release;
BOOL ReleaseCandidate;
BOOL FinalRelease;
BOOL Demo;
TCHAR Cargo[VER_BUFFER_SIZE];
TCHAR Author[MAX_PATH];
TCHAR Name[MAX_PATH];
TCHAR Date[21];
TCHAR IniFile[MAX_PATH];
TCHAR Copyrights[MAX_PATH];
TCHAR Company[MAX_PATH];
} FOCUSVersion;
int VerMajor Contains the major version number. Ex. : 3
int VerMinor Contains the minor version number. Ex. : 11
TCHAR Revision revision number. Ex. : "0023a"
int Counter Application counter. Ex. : 2015
BOOL Alpha Contains a flag. Alpha version? Ex. : .F.
BOOL Beta Contains a flag. Beta version? Ex. : .T.
BOOL PreRelease Contains a flag. Pre-release version? Ex. : .F.
BOOL Release Contains a flag. Release? Ex. : .F.
BOOL FinalRelease Contains a flag. Final release? Ex. : .F.
BOOL Demo Is it a demo version? Ex. : .F.
TCHAR Cargo[257] Your own field. Ex. : "Temporary implementation of messaging

functions"
TCHAR Author[MAX_PATH] Author name. Ex. : "Peter Cumsay"
TCHAR Name[MAX_PATH] Application title. Ex. : "My Application"
TCHAR Date[21] Date and time information. Ex. : "31-01-1994 15:30"
TCHAR IniFile[MAX_PATH] Application INI file. Ex. : "C:\MYAPPL\MYAPPL.INI"

Version Functions
TCHAR Copyrights[MAX_PATH] Copyrights. Ex. : "1988-1998 FastWrite rights reserved"
TCHAR Company[MAX_PATH] Company. Ex. : "FastWrite Asia Co., Ltd."
Usually, an application resides in its alpha phase when not all the expected functionalities are implemented. An
application resides in its beta phase when all the functionalities and features are included in the project but should still
be fully tested.
When FOCUS.FLL is used in conjunction with FOCUS.VCX , the Program class parses version information from the
classes themselves and put these values in the corresponding FOCUS.FLL slots. For example, when setting up the
Version.Major property of the Program class, when the program is run, FOCUS.VCX puts the Version.Major
property value in FOCUS.FLL thanks to the VER_major() version. This makes it possible for FOCUS.FLL to gather
information about the applications that are written and that use it. This information is later on stored in FDB files (see
FDB_*() functions).

Version Functions
VER_alpha() : Gets/sets the alpha flag.

Syntax
VER_alpha( [lSetting] )  lCurSetting
Parameters
lSetting new alpha setting. Setting this flag affects the beta and PreRelease flags.
Returns
lCurSetting current alpha setting.
Example
VER_alpha( .T. )
? VER_alpha() && .T.
? VER_beta() && .F.
? VER_prerel() && .F.
VER_author() : Gets/sets the author name.

Syntax
VER_author( [szNewAuthor] )  szCurAuthor
Parameters
szNewAuthor name of author of the application. Parameter may not exceed 40 characters.
Returns
szCurAuthor current author setting.
Example
VER_author( "Dave Kallander" )
? VER_auhor() && "Dave Kallander"
VER_beta() : Gets/sets the beta flag.

Syntax
VER_beta( [lSetting] )  lCurSetting
Parameters
lSetting new beta setting. Setting this flag affects the alpha and PreRelease flags.
Returns
lCurSetting current beta setting.
Example
VER_beta( .T. )
? VER_beta() && .T.
? VER_alpha() && .F.
? VER_prerel() && .F.

Version Functions
VER_cargo() : Gets/sets the cargo member. You can write
whatever information you’d like to.
Syntax
VER_cargo( [szNewCargo] )  szCurCargo
Parameters
szNewCargo new string to write to cargo member. Parameter may not exceed 256 characters.
Returns
szCurCargo current string contained in cargo member.
Example
VER_cargo( "This application is a test" )
? VER_cargo() && "This application is a test"
VER_cpyrig() : Gets/sets the application copyrights.

Alias
VER_copyrights()
Syntax
VER_cpyrig( [szNewRights] )  szCurRights
Parameters
szNewRights copyrights of application. Parameter may not exceed 40 characters.
Returns
szCurRights current copyrights setting.
Example
VER_cpyrig( "Copyrights 1994 - FastWrite SC" )
? VER_cpyrig() && " Copyrights 1994 - FastWrite SC "
VER_counte() : Gets/sets the application counter.

Alias
VER_counter() , VER_ApplCounter() .
Syntax
VER_counte( [nCounter] )  nCurCounter
Parameters
nCounter the internal application counter.
Returns
nCurCounter current application counter.

Version Functions
Example
VER_counte( VER_counte() + 1 ) && Increments counter
VER_company() : Gets/sets the Company member.

Syntax
VER_company( [szCompany] )  szCurCompany
Parameters
szCompany the company that created the application.
Returns
szCurCompany current company.
Example
VER_company( "Double Team Co., Ltd." )
VER_date() : Gets/sets the date field.

Syntax
VER_date( [szDateTime] )  szCurDateTime
Parameters
szDateTime new date and time setting.
Returns
szCurDateTime current date and time setting. Parameter may not exceed 20 characters.
Example
VER_date( "25-04-1994 12:33" )
? VER_date() && "25-04-1994 12:33"
VER_demo() : Gets/sets the demo flag.

Syntax
VER_demo( [lSetting] )  lCurSetting
Parameters
lSetting new demo setting. Setting this flag affects all related flags (alpha, beta, release, etc.).
Returns
lCurSetting current demo setting.
Example
VER_demo( .T. )
? VER_demo() && .T.

Version Functions
VER_FinalRelease() : Gets/sets the Final Release flag.
Syntax
VER_FinalRelease( [lSetting] )  lCurSetting
Parameters
lSetting new Final Release setting. Setting this flag affects all related flags (alpha, beta, release, etc.).
Returns
lCurSetting current Final Release setting.
Example
VER_FinalRelease( .T. )
? VER_FinalRelease() && .T.
? VER_beta() && .F.
VER_GetFileVersionInfo() : Determines executable version

information.
Special
VER_GetFileVersionInfo() works only with Win32 file images. It does not work with 16-bit Windows file images.
When this function was originally created, Visual FoxPro didn't get any function of that type. With the advent of Visual
FoxPro 6.0, the AGETFILEVERSION() function appeared, which basically can do the same thing although there is no
exact match between FOCUS.FLL and VFP.
Executable files such as .EXE, .DLL, .FLL and others, can contain multiple version information structures. For example,
the copyrights might be stored in French, Dutch English, etc. Each language (I should say "Each language and code
page combination"), the executable can contain a unique versioin information structure.
There is a significant difference between FOCUS.FLL and Visual FoxPro, because FOCUS.FLL makes it easy to extract
any language information where VFP only returns the first information it gets out of the executable.
Because DLLs are not re-entrant you cannot use VER_GetFileVersionInfo() of FOCUS.FLL to determine
version information of FOCUS.FLL itself.
Alias
GetFileVersionInfo() , GetFileVersion() .
Syntax
VER_GetFileVersionInfo( szFile,nSetting[,szLangCP] )  szSetting
Parameters
szFile filename string.
nSetting type of setting to return.

Version Functions
Value Description AGetFileVersion() of VFP
1 ProductName 10
2 ProductVersion 11
3 OriginalFilename 8
4 FileDescription 3
5 FileVersion 4
6 CompanyName 2
7 LegalCopyright 6
8 LegalTrademarks 7
9 InternalName 5
10 PrivateBuild 9
11 SpecialBuild 12
12 Comments 1
szLangCP combination of Language ID + code page. Optional parameter. If this parameter is not passed,
FOCUS.FLL always retrieves the file version information in the following order:
1. User language ID + Console Code Page
2. French Belgian
3. French Standard
4. Dutch Belgian
5. Dutch Standard
6. English US
Should you wish to retrieve other file version info for additional languages, just mention it to us,
and we'll implement thse new numbers.
Useful Language IDs

Value Description
"0409" English US
"080C" French Belgian
"040C" French Standard
"0813" Dutch Belgian
"0413" Dutch Standard
Useful Code Page Ids

Value Description
"04E2" Windows Latin-2
"04E4" Windows Multilingual
"04B0" Unicode
Returns
szSetting file-version info member.
Example
LOCAL szFile
szFile = "D:\Program Files\Microsoft Office97\Office\WINWORD.EXE"
? VER_GetFileVersionInfo( szFile,1 ) && Microsoft® Word for Windows® 97

? VER_GetFileVersionInfo( szFile,2 ) && 8.0
? VER_GetFileVersionInfo( szFile,3 ) && WINWORD.EXE
? VER_GetFileVersionInfo( szFile,4 ) && Microsoft Word for
&& Windows® 97 application file
? VER_GetFileVersionInfo( szFile,5 ) && 8.0

Version Functions
? VER_GetFileVersionInfo( szFile,6 ) && Microsoft Corporation
? VER_GetFileVersionInfo( szFile,7 ) && Copyright (C) Microsoft
&& Corporation 1983-1996.
? VER_GetFileVersionInfo( szFile,8 ) &&
? VER_GetFileVersionInfo( szFile,9 ) && msword
szFile = "FOCUS.FLL"
&& We are not going to use any language setting. Therefore, FOCUS.FLL will retrieve
&& the French Belgian information first, and that's what will be returned
? VER_GetFileVersionInfo( szFile,1 ) && FastWrite FOCUS
? VER_GetFileVersionInfo( szFile,2 ) && 6, 5, 3015a, 0
? VER_GetFileVersionInfo( szFile,3 ) && FOCUS.fll
? VER_GetFileVersionInfo( szFile,4 ) && FOCUS.FLL pour Visual FoxPro 5.0 et 6.0
? VER_GetFileVersionInfo( szFile,5 ) && 6, 5, 3015a, 0
? VER_GetFileVersionInfo( szFile,6 ) && FastWrite
? VER_GetFileVersionInfo( szFile,7 ) && Droits réservés © 1995-1999 FastWrite Belgium
? VER_GetFileVersionInfo( szFile,9 ) && FOCUS
? VER_GetFileVersionInfo( szFile,12 ) && Auteur : Pat Y. Boens
&& Now, we are going to extract the File Version Information in English US,
&& Code Page: Windows Multilingual
? VER_GetFileVersionInfo( szFile,1 ,"040904E4" ) && FastWrite FOCUS
? VER_GetFileVersionInfo( szFile,2 ,"040904E4" ) && 6, 5, 3015a, 0
? VER_GetFileVersionInfo( szFile,3 ,"040904E4" ) && FOCUS.fll
? VER_GetFileVersionInfo( szFile,4 ,"040904E4" ) && FOCUS.FLL for Visual FoxPro 5.0
&& and 6.0
? VER_GetFileVersionInfo( szFile,5 ,"040904E4" ) && 6, 5, 3015a, 0
? VER_GetFileVersionInfo( szFile,6 ,"040904E4" ) && FastWrite
? VER_GetFileVersionInfo( szFile,7 ,"040904E4" ) && Copyrights © 1995-1999
&& FastWrite Belgium
? VER_GetFileVersionInfo( szFile,8 ,"040904E4" ) &&
? VER_GetFileVersionInfo( szFile,9 ,"040904E4" ) && FOCUS
? VER_GetFileVersionInfo( szFile,10,"040904E4" ) &&
? VER_GetFileVersionInfo( szFile,11,"040904E4" ) &&
? VER_GetFileVersionInfo( szFile,12,"040904E4" ) && Author : Pat Y. Boens
VER_ini() : Gets/sets the INI file field.

Alias
VER_inifile()
Syntax
VER_ini( [szINIFile] )  szCurINIFile
Parameters
szINIFile new INI file setting.
Returns
szCurINIFile current INI file setting. Parameter may not exceed 64 characters.
Example
VER_ini( "POWER.INI" )
? VER_ini() && "POWER.INI"

Version Functions
VER_init() : Initializes C structure members.
Syntax
VER_init()  .T.
Parameters
None.
Returns
.T. the function always returns .T. . The VER_init() function initializes all the members of the
internal C structure. It is called upon load of FOCUS.FLL .
Example
VER_init()
VER_name( "Commercial Companion" )
VER_ini( "COMP.INI" )
VER_alpha( .T. )
VER_major( 3 )
VER_minor( 11 )
VER_date("1994/01/21 02:30 pm" )
VER_author( "Marco Polo" )
VER_demo( .T. )
VER_cargo( "DEMO version. Copyrights Plus Soft, Inc." )
VER_LastVersion() : Returns the file stamp of VER functions.

Remark
Syntax
VER_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\VERSION.C-Mon Oct 19 15:55:22 1998" .
VER_major() : Gets/sets the major version number.

Syntax
VER_major( [nMajor] )  nCurMajor
Parameters

Version Functions
Returns
nCurMajor current major version number.
Example
VER_major( 3 )
VER_minor( 10 )
? ALLTRIM( STR( VER_minor() ) ) + "." + ;
ALLTRIM( STR( VER_minor() ) ) && "3.10"
VER_minor() : Gets/sets the minor version number.

Syntax
VER_minor( [nMinor] )  nCurMinor
Parameters
Returns
nCurMinor current minor version number.
Example
VER_major( 3 )
VER_minor( 10 )
? ALLTRIM( STR( VER_minor() ) ) + "." ;
ALLTRIM( STR( VER_minor() ) ) && "3.10"
VER_name() : Gets/sets the application name.

Alias
VER_applname()
Syntax
VER_name( [szApplName] )  szCurApplName
Parameters
szApplName application name. Parameter may not exceed 60 characters.
Returns
szCurApplName current application name.
Example
VER_name( "Easy Learning - Home Library" )
? VER_name() && "Easy Learning - Home Library"
VER_prerel() : Gets/sets the pre-release flag.

Alias
VER_PreRelease()
Syntax
VER_prerel( [lSetting] )  lCurSetting

Version Functions
Parameters
lSetting new PreRelease setting. Setting this flag affects the alpha and beta flags.
Returns
lCurSetting current PreRelease setting.
Example
VER_prerel( .T. )
? VER_prerel() && .T.
? VER_beta() && .F.
VER_Release() : Gets/sets the Release flag.

Syntax
VER_Release( [lSetting] )  lCurSetting
Parameters
lSetting new Release setting. Setting this flag affects all related flags (alpha, beta, final release, etc.).
Returns
lCurSetting current Release setting.
Example
VER_FinalRelease( .T. )
? VER_FinalRelease() && .T.
? VER_beta() && .F.
VER_ReleaseCandidate() : Gets/sets the Release Candidate

flag.
Syntax
VER_ReleaseCandidate( [lSetting] )  lCurSetting
Parameters
lSetting new Release Candidate setting. Setting this flag affects all related flags (alpha, beta, final
release, etc.).
Returns
lCurSetting current Release Candidate setting.
Example
VER_ReleaseCandidate( .T. )
? VER_ReleaseCandidate() && .T.
? VER_beta() && .F.

Version Functions
VER_Revision() : Gets/sets the revision number.
Syntax
VER_Revision( [szRevision] )  szCurRevision
Parameters
szRevision revision number.
Returns
szCurRevision current revision number.
Example
VER_name( "My Application" )
VER_major( 3 )
VER_minor( 1 )
VER_revision( "0017a" )
? VER_name() + " " + ALLTRIM(STR(VER_major())) + "." + ;
PADL( VER_minor(),2,"0" ) + "." + ;
VER_revision() && "My Application 3.01.0017a"

Video Functions
Video Functions

Video Functions
VID_close() : Closes the AVI device.

Syntax
VID_close()  szReturn
Parameters
None.
Returns
szReturn ????.
VID_end() : Sets the AVI to the end position.

Syntax
VID_end()  szReturn
Parameters
None.
Returns
szReturn ????.
VID_home() : Sets the AVI to the start position.

Syntax
VID_home()  szReturn
Parameters
None.
Returns
szReturn ????.
VID_LastError() : Determines the last error that occurred within

the CD_*() functions.
Alias
In fact, the VID_*() functions are implemented in the MCI.C source file because it belongs to this section. The same
goes for CD_*() functions. Therefore, VID_LastError() is mapped to MCI_LastError() . The following functions
are all synonyms :
CD_GetLastError(), CD_GetLastError(), VID_LastError(), VID_GetLastError(), MCI_LastError(),
MCI_GetLastError())
Syntax
VID_LastError()  szLastError

Video Functions
Parameters
None.
Returns
szLastError string describing the last error that occurred using the CD_*() functions.
VID_LastVersion() : Returns the file stamp of VID functions.

Remark
Syntax
VID_LastVersion()  szLastVersion
Parameters
None.
Returns
VID_loff() : Sets the AVI audio left off.

Syntax
VID_loff()  .T.
Parameters
None.
Returns
VID_lon() : Sets the AVI audio left on.

Syntax
VID_lon()  .T.
Parameters
None.
Returns

Video Functions
VID_off() : Sets the AVI audio off.
Syntax
VID_off()  .T.
Parameters
None.
Returns
VID_on() : Sets the AVI audio on.

Syntax
VID_on()  .T.
Parameters
None.
Returns
VID_open() : Opens the AVI device.

Syntax
VID_open( szDevice )  szReturn
Parameters
szDevice device to open.
Returns
szReturn ????.
VID_play() : Plays the AVI device.

Syntax
VID_end()  szReturn
Parameters
None.
Returns
szReturn ????.

Video Functions
VID_pause() : Pauses the AVI device.
Syntax
VID_roff()  .T.
Parameters
None.
Returns
VID_ron() : Sets the AVI audio right on.

Syntax
VID_ron()  .T.
Parameters
None.
Returns

WHOIS Functions
WHOIS Functions

WHOIS Functions
Functions Synopsis
WHOIS functions of FOCUS.FLL allow users to query information in central databases regarding users, hosts, company
addresses, and phone numbers.
The WHOIS Protocol
The WHOIS protocol is part of the TCP/IP stack in that it is a service based on TCP/IP (port 43). Its primary purpose is
to extract information from a central repository that resides on the InterNIC server (Internet Network Information
Center).
The WHOIS protocol is based on the query/response model: when a query is sent, the recipient sends a response back
and drops the connection.
The WHOIS Request
The string that is sent as a request to the server must be terminated with a carriage return/line feed (<CRLF>,
CHR(13) + CHR(10) ).

WHOIS Functions
WHOIS_LastError() : Last error encountered in WHOIS

functions.
Syntax
WHOIS_LastError()  szLastError
Parameters
None.
Returns
szLastError last error that occurred while using the WHOIS_*() functions.
Example
WHOIS_LastVersion() : Returns the file stamp of WHOIS

functions.
Remark
Syntax
WHOIS_LastVersion()  szLastVersion
Parameters
None.
Returns
WHOIS_whois() : Queries a central repository for information

regarding users, hosts, company addresses, and phone
numbers.
Alias
WhoIs(), WHOIS_whois()
Syntax
WHOIS_query( szHost,szQuery )  szInfo
Parameters
szHost WHOIS Server

WHOIS Functions
szQuery Domain from which to obtain the WHOIS information.
Some WHOIS servers

whois.opensrs.net
whois.internic.com
whois.gandi.net
whois.register.com
whois.tucows.com
whois.directnic.com
whois.ripe.net
Returns
szInfo Server response or an empty string if an error occurred. You can use the
WHOIS_LastError() function to retrieve a more detailed explanation.
Error code Meaning

"WSANOTINITIALISED" A successful WSAStartup() call must occur before using this
function.
"WSAENETDOWN" The network subsystem has failed.
"WSAEFAULT" The buf parameter is not completely contained in a valid part of
the user address space.
"WSAENOTCONN" The socket is not connected.
"WSAEINTR" The (blocking) call was canceled through
WSACancelBlockingCall() .
"WSAEINPROGRESS" A blocking Windows Sockets 1.1 call is in progress, or the
service provider is still processing a callback function.
"WSAENETRESET" The connection has been broken due to the keep-alive activity
detecting a failure while the operation was in progress.
"WSAENOTSOCK" The descriptor is not a socket.
"WSAEOPNOTSUPP" MSG_OOB was specified, but the socket is not stream-style
such as type SOCK_STREAM, OOB data is not supported in the
communication domain associated with this socket, or the
socket is unidirectional and supports only send operations.
"WSAESHUTDOWN" The socket has been shut down; it is not possible to receive on
a socket after shutdown has been invoked with how set to
SD_RECEIVE or SD_BOTH.
"WSAEWOULDBLOCK" The socket is marked as nonblocking and the receive operation
would block.
"WSAEMSGSIZE" The message was too large to fit into the specified buffer and
was truncated.
"WSAEINVAL" The socket has not been bound with bind, or an unknown flag
was specified, or MSG_OOB was specified for a socket with
SO_OOBINLINE enabled or (for byte stream sockets only) len
was zero or negative.
"WSAECONNABORTED" The virtual circuit was terminated due to a time-out or other
failure. The application should close the socket as it is no longer
usable.
"WSAETIMEDOUT" The connection has been dropped because of a network failure
or because the peer system failed to respond.
"WSAECONNRESET" The virtual circuit was reset by the remote side executing a
hard or abortive close. The application should close the socket
as it is no longer usable. On a UPD-datagram socket this error
would indicate that a previous send operation resulted in an
ICMP "Port Unreachable" message.
Example
LOCAL szHost
LOCAL szDomain
m.szHost = "whois.tucows.com"
m.szDomain = "www.fastwrite.com"
? WHOIS_whois( m.szHost,m.szDomain )
&& This will display the following information:

WHOIS Functions
Registrant:
Fastwrite
rue A. Bracke 9
Kraainem, 1950
BE
Domain name: FASTWRITE.COM
Administrative Contact:
Boens, Pat pat.boens@fastwrite.com
rue A. Bracke 9
Kraainem, 1950
BE
+32.27208228
Technical Contact:
DNS Masters, Belgacom Skynet dnsmaster@skynet.be
Carlistraat 2
Brussels, 1140
BE
+32.27061311 Fax: +32.27061312
Registration Service Provider:

Belgacom NV/SA, dnsmaster@belgacom.be
080023452
+32.27061194 (fax)
http://www.belgacom.be/
This company may be contacted for domain login/passwords,
DNS/Nameserver changes, and general domain support questions.
Registrar of Record: TUCOWS, INC.

Record last updated on 09-Aug-2002.
Record expires on 19-Nov-2004.
Record Created on 20-Nov-1997.
Domain servers in listed order:

NS1.SKYNET.BE
NS3.SKYNET.BE
NS4.SKYNET.BE
NS2.SKYNET.BE
The Data in the Tucows Registrar WHOIS database is provided to you by Tucows
for information purposes only, and may be used to assist you in obtaining
information about or related to a domain name's registration record.
Tucows makes this information available "as is," and does not guarantee its
accuracy.
By submitting a WHOIS query, you agree that you will use this data only for
lawful purposes and that, under no circumstances will you use this data to:
a) allow, enable, or otherwise support the transmission by e-mail,
telephone, or facsimile of mass, unsolicited, commercial advertising or
solicitations to entities other than the data recipient's own existing
customers; or (b) enable high volume, automated, electronic processes that
send queries or data to the systems of any Registry Operator or
ICANN-Accredited registrar, except as reasonably necessary to register
domain names or modify existing registrations.
The compilation, repackaging, dissemination or other use of this Data is

expressly prohibited without the prior written consent of Tucows.
Tucows reserves the right to terminate your access to the Tucows WHOIS
database in its sole discretion, including without limitation, for excessive
querying of the WHOIS database or for failure to otherwise abide by this
policy.
Tucows reserves the right to modify these terms at any time.
By submitting this query, you agree to abide by these terms.
NOTE: THE WHOIS DATABASE IS A CONTACT DATABASE ONLY. LACK OF A DOMAIN

RECORD DOES NOT SIGNIFY DOMAIN AVAILABILITY.

Window Functions
Windows Functions

Window Functions
Functions Synopsis
FOCUS.FLL gives the developer tighter control over FoxPro and non FoxPro windows through an impressive set of
functions.
Visual FoxPro works with window handles that are WHANDLE values. Windows works with handles that are HWND
values. These two types of window handles are not compatible. You can easily turn a WHANDLE to a HWND thanks to
the WIN_WHandleToHwnd() function of FOCUS. The contrary is not possible. Don't use WHANDLE s for HWND s nor the
opposite : this would generate illegal operations.

Window Functions
WIN_bottom() : Window bottom border position in pixels.

Caution
Don't use HWND s in place of WHANDLE s with this function otherwise Visual FoxPro will generate illegal operations.
Syntax
WIN_bottom( nWHandle|szTitle )  nBottom
Parameters
nWHandle window handle (WHANDLE).
or…
szTitle title of the window.
Returns
nBottom window bottom border position in pixels or –1 if error.
WIN_ClearOval() : Deletes an elliptical region created with

WIN_MakeOval().
Syntax
WIN_ClearOval( nHwnd )  lSuccess
Parameters
nHwnd Window handle (can be obtained by a call to WIN_hwnd() ).
Returns
lSuccess .T. if the elliptic region was successfully deleted; .F. if the function failed.
Example
LOCAL hWnd
WITH ThisForm

ENDIF
m.hWnd = WIN_hwnd( This.caption )
.Width = 324
.Height = 146
DODEFAULT()
WIN_MakeOval( m.hWnd )
ENDWITH

LOCAL hWnd

Window Functions
WIN_ClearOval( m.hWnd )
CLEAR EVENTS
The example of above creates the an elliptical form. The elliptical form is created in a similar way than the
GDI_CreateEllipticRegion() function but this time we use the WIN_MakeOval() function that is much simpler
to use. To beautify the presentation of the form, we have created a JPG file that fills perfectly the ellipse.
WIN_Destroy() : Destroys the specified window.

Alias
DestroyWindow() .
Remarks
The WIN_Destroy() function does not support the WM_NCDESTROY or the WM_PARENTNOTIFY message. It does not
destroy children of the specified window. It does not flush the thread message queue. A thread cannot use
WIN_Destroy() to destroy a window created by a different thread.
Syntax
WIN_Destroy( nHwnd )  lSuccess
Parameters
nHwnd window handle (HWND).
Returns
lSuccess .T. if the nHwnd window has been destroyed; .F. if not.
WIN_DestroyIcon() : Destroys a given icon.

Syntax
WIN_DestroyIcon( nIcon )  lSuccess
Parameters
nIcon icon handle (typically returned by WIN_GetIcon() ).
Returns
lSuccess .T. if the icon was successfully destroyed; .F. if not.
Example
LOCAL hwnd
LOCAL hdc

Window Functions
LOCAL hIcon
LOCAL szFile
m.szFile = "FOCUS.FLL" && File from which an icon will be extracted
m.hwnd = WIN_hwnd( "Microsoft Visual FoxPro" ) && Window handle

m.hdc = WIN_GetWindowDC( m.hwnd ) && Obtain a Device Context
m.hIcon = WIN_GetIcon( m.szFile,0 ) && Get 1st icon from FOCUS.FLL
WIN_DrawIcon( m.hdc,100,150,m.hIcon ) && Draw the icon

WIN_DestroyIcon( m.hIcon ) && Destroy the icon (free memory)
WIN_ReleaseDC( m.hwnd,m.hdc ) && Release Device Context
WIN_dialog() : Displays a dialog box that is the specified color

scheme and contains the specified body text and button
text.
Syntax
WIN_Dialog( nColorScheme,szBody,szButton1,szButton2,szButton3 )  nButton
Parameters
nColorScheme color scheme to use.
szBody text to display in the dialog.
szButton1 prompt that will appear on the first button.
szButton2 prompt that will appear on the second button.
szButton3 prompt that will appear on the third button.
Returns
nButton the button number that was pressed to quit the dialog.
Example
WIN_dialog( 0,"Text in dialog","1","2","3" )
This call causes the following dialog to be displayed :
WIN_DrawAnimatedRects() : Draws a wire-frame rectangle and

animates it to indicate the opening of an icon or the
minimizing or maximizing of a window.
Syntax
WIN_DrawAnimatedRects( nHwnd,nTop1,nLeft1,nBottom1,nRight1,
nTop2,nLeft2,nBottom2,nRight2,
nAni )  lSuccess

Window Functions
Parameters
nHwnd window handle.
nTop1 top position of the starting rectangle.
nLeft1 left position of the starting rectangle.
nBottom1 bottom position of the starting rectangle.
nRight1 right position of the starting rectangle.
nTop2 top position of the ending rectangle.
nLeft2 left position of the ending rectangle.
nBottom2 bottom position of the ending rectangle.
nRight2 right position of the ending rectangle.
nAni animation ID (use 3).
Returns
lSuccess .T. if the window was properly animated; .F. if not.
Example
LOCAL hwnd
hwnd = WIN_hwnd( "frmTest3D" )
WIN_DrawAnimateRects( hwnd,0,0,0,0,300,300,600,600,3 )
WIN_DrawEdge() : Draws one or more edges of rectangle

Syntax
WIN_DrawEdge( nTop,nLeft,nBottom,nRight,nDC,nEdge,nFlags )  lSuccess
Parameters
nTop y-coordinate of the upper-left corner of the rectangle.
nLeft x-coordinate of the upper-left corner of the rectangle.
nBottom y-coordinate of the lower-right corner of the rectangle.
nRight x-coordinate of the lower-right corner of the rectangle.
nDC handle to device context.
nEdge type of inner and outer edge to draw.
Manifest Constant Value

BDR_RAISEDOUTER 0x0001
BDR_SUNKENOUTER 0x0002
BDR_RAISEDINNER 0x0004
BDR_SUNKENINNER 0x0008
BDR_OUTER 0x0003
BDR_INNER 0x000c
BDR_RAISED 0x0005
BDR_SUNKEN 0x000a

Window Functions
EDGE_RAISED (BDR_RAISEDOUTER | BDR_RAISEDINNER)
EDGE_SUNKEN (BDR_SUNKENOUTER | BDR_SUNKENINNER)
EDGE_ETCHED (BDR_SUNKENOUTER | BDR_RAISEDINNER)
EDGE_BUMP (BDR_RAISEDOUTER | BDR_SUNKENINNER)
nFlags type of border.
Manifest Constant Value Description

BF_LEFT 0x0001
BF_TOP 0x0002
BF_RIGHT 0x0004
BF_BOTTOM 0x0008
BF_TOPLEFT BF_TOP | BF_LEFT
BF_TOPRIGHT BF_TOP | BF_RIGHT
BF_BOTTOMLEFT BF_BOTTOM | BF_LEFT
BF_BOTTOMRIGHT BF_BOTTOM | BF_RIGHT
BF_RECT BF_LEFT | BF_TOP |
BF_RIGHT | BF_BOTTOM
BF_DIAGONAL 0x0010
BF_DIAGONAL_ENDTOPRIGHT BF_DIAGONAL |
BF_TOP |
BF_RIGHT
BF_DIAGONAL_ENDTOPLEFT BF_DIAGONAL |
BF_TOP |
BF_LEFT
BF_DIAGONAL_ENDBOTTOMLEFT BF_DIAGONAL |
BF_BOTTOM | BF_LEFT
BF_DIAGONAL_ENDBOTTOMRIGHT BF_DIAGONAL |
BF_BOTTOM | BF_RIGHT
BF_MIDDLE 0x0800 Fill in the middle
BF_SOFT 0x1000 For softer buttons
BF_ADJUST 0x2000 Calculate the space left
over
BF_FLAT 0x4000 For flat rather than 3D
borders
BF_MONO 0x8000 For monochrome borders
For diagonal lines, the BF_RECT flags specify the end point of the vector bounded by the
rectangle parameter.
Returns
lSuccess .T. indicates that the function was successful; .F. if not.
WIN_DrawIcon() : Draws a given icon.

Remark
Visual FoxPro redraws the windows/forms so quickly that you may not notice that the icon was drawn.
Syntax
WIN_DrawIcon( nDC,nX,nY,nIcon )  lSuccess
Parameters
nDC handle to device context.
nX X position where the icon must be displayed (top).
nY Y position where the icon must be displayed (top)
nIcon icon handle.

Window Functions
Returns
lSuccess .T. if the icon was successfully drawn; .F. if not.
Example
LOCAL hwnd
LOCAL hdc
LOCAL hIcon
LOCAL szFile


WIN_EnumChildren() : Enumerates the child windows that

belong to the specified parent window.
Remark
The WIN_EnumChildren() function cannot act in one single shot. Internally, it provides Windows with an internal
function pointer that will be executed for each separate window. It is when this internal function is completed that
FOCUS.FLL will be able to deliver all the window handles through its WIN_GetChildren() function. In very simple
terms, determining all child window of a specified parent window is done in 2 steps: first a call to
WIN_EnumChildren() and then a call to WIN_GetChildren() .
Alias
EnumChildren()
Syntax
WIN_EnumChildren( [nHwnd] )  lSuccess
Parameters
nHwnd optional window handle (HWND). If not passed, the function uses the active window.
Returns
Example
LOCAL szWindows
LOCAL OldSep
LOCAL szTitle
LOCAL nTokens
LOCAL i
&& This example starts by enumerating all the child windows of the Desktop of Windows.
&& If the EnumChildren() call is successful, it asks FOCUS.FLL to return all the
&& handles that were found (WIN_GetChildren()). This function actually returns a
&& string where each Window Handle is separated from the other by a caret
&& ("2080^344^612^2572", for example). We then use token functions to extract each
&& window handle (STR_numtok() to determine how many window handles were found, and
&& STR_ntoken() to extract each separate handle). Once the handle is excerpted from
&& the string, it is used by the GetWindowTitle() function to determine the Title
&& of each window. If the titkle is not empty (case when a window is hidden, or when
&& it has no title), it is displayed along with the associated window handle.
IF ( WIN_EnumChildren( GetDesktopWindow() ) )
Window Functions
szWindows = WIN_GetChildren()
OldSep = STR_setsep( "^" )
nTokens = STR_numtok( szWindows )
FOR i = 1 TO nTokens
szHandle = STR_ntoken( i,szWindows )
szTitle = GetWindowTitle( VAL( szHandle ) )
IF ( ! EMPTY( szTitle ) )
? szTitle,szHandle
ENDIF
NEXT
ENDIF
WIN_EnumWindows() : Enumerates all top-level windows on

the screen.
Remark
The WIN_EnumWindows() function cannot act in one single shot. Internally, it provides Windows with an internal
FOCUS.FLL will be able to deliver all the window handles through its WIN_GetWindows() function. In very simple
WIN_EnumWindows() and then a call to WIN_GetWindows() .
Alias
EnumWindows()
Syntax
WIN_EnumWindows()  lSuccess
Parameters
None.
Returns
Example
LOCAL szWindows
LOCAL OldSep
LOCAL szTitle
LOCAL nTokens
LOCAL i
&& This example starts by enumerating all the top level windows.
IF ( WIN_EnumWindows() )
m.szWindows = WIN_GetWindows()
m.nTokens = STR_numtok( m.szWindows )
m.szHandle = STR_ntoken( i,m.szWindows )
m.szTitle = GetWindowTitle( VAL( m.szHandle ) )
IF ( ! EMPTY( m.szTitle ) )
? m.szTitle,m.szHandle
ENDIF
NEXT
Window Functions
ENDIF
WIN_Flash() : Flashes the specified window once.

Syntax
WIN_Flash( nHwnd|szCaption,lStatus )  lSuccess
Parameters
nHwnd window handle (HWND)
or
szCaption title of the window that must flash.

lStatus specifies whether the window is to be flashed or returned to its original state. The window is
flashed from one state to the other if this parameter is .T. . If it is .F., the window is returned
to its original state (either active or inactive). When an application is iconic (minimized), if this
parameter is .T. , the taskbar window button flashes active/inactive. If it is .F. , the taskbar
window button flashes inactive, meaning that it does not change colors. It flashes, as if it were
being redraw, but it does not provide the visual invert clue to the user.
Returns
lSuccess the return value specifies the window's state before the call to the WIN_Flash() function. If
the window was active before the call, the return value is .T. . If the window was not active
before the call, the return value is .F..
WIN_GetActiveWindow() : Retrieves window handle (HWND) of

the current window.
Alias
GetActiveWindow()
Syntax
WIN_GetActiveWindow()  nHwnd
Parameters
None.
Returns
WIN_GetChildren() : Retrieves all child window handles

obtained by a call to WIN_EnumChildren().
Remark
The WIN_EnumChildren() function cannot act in one single shot. Internally, it provides Windows with an internal
function pointer that will ge executed for each separate window. It is when this internal function is completed that
FOCUS.FLL will be able to deliver all the window handles through its WIN_GetChildren() function. In very simple
WIN_EnumChildren() and then a call to WIN_GetChildren() .

Window Functions
Alias
GetWindows(), GetChildren()
Syntax
WIN_GetChildren()  szChildren
Parameters
None.
Returns
szChildren a tokenized string with all window handles or an empty string ( "") if no child window is found.
Each token is separated from the other by a caret (^).
Example
LOCAL szWindows
LOCAL OldSep
LOCAL szTitle
LOCAL nTokens
LOCAL i
&& This example starts by enumerating all the child windows of the Desktop of Windows.
&& If the EnumChildren() call is successful, it asks FOCUS.FLL to return all the
&& handles that were found (WIN_GetChildren()). This function actually returns a
&& string where each Window Handle is separated from the other by a caret
&& ("2080^344^612^2572", for example). We then use token functions to extract each
&& window handle (STR_numtok() to determine how many window handles were found, and
&& STR_ntoken() to extract each separate handle). Once the handle is excerpted from
&& the string, it is used by the GetWindowTitle() function to determine the Title
&& of each window. If the titkle is not empty (case when a window is hidden, or when
&& it has no title), it is displayed along with the associated window handle.
IF ( WIN_EnumChildren( GetDesktopWindow() ) )
szWindows = WIN_GetChildren()
OldSep = STR_setsep( "^" )
nTokens = STR_numtok( szWindows )
szHandle = STR_ntoken( i,szWindows )
szTitle = GetWindowTitle( VAL( szHandle ) )
IF ( ! EMPTY( szTitle ) )
? szTitle,szHandle
ENDIF
NEXT
ENDIF
WIN_GetClassName() : Retrieves the name of the class to

which the specified window belongs.
Alias
GetClassName()
Syntax
WIN_GetClassName( nHwnd )  szClass
Parameters
nHwnd the handle to the window and, indirectly, the class to which the window belongs.

Window Functions
Returns
szClass class name string.
Example
LOCAL nHwnd
nHwnd = WIN_GetHandle( "Microsoft Word – Document1" )
IF ( nHwnd != 0 )
szClass = GetClassName( nHwnd ) && "OpusApp"
ENDIF
WIN_GetClientArea() : Retrieves the dimensions of the

bounding rectangle of the specified window.
Special
The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen. This function is
particularly helpful when it comes down to know a control's absolute coordinates. For example, it can be used in
conjunction with MOU_ClipCursor() .
Each time a window is moved, you need to reissue the WIN_GetClientArea() function.
Alias
GetClientArea()
Syntax
WIN_GetClientArea( nHwnd,@nTop,@nLeft,@nBottom,@nRight )  lSuccess
Parameters
nTop y-coordinate of the upper-left corner of the window. Must be passed by reference.
nLeft x-coordinate of the upper-left corner of the window. Must be passed by reference.
nBottom y-coordinate of the lower-right corner of the window. Must be passed by reference.
nRight x-coordinate of the lower-right corner of the window. Must be passed by reference.
Returns
Example
LOCAL hwnd && HWND handle
LOCAL top && y-coordinate of the upper-left corner of the window
LOCAL left && x-coordinate of the upper-left corner of the window
LOCAL bottom && y-coordinate of the lower-right corner of the window
LOCAL right && x-coordinate of the lower-right corner of the window
top = 0
left = 0
bottom = 0
right = 0
DO FORM "testDC"
hwnd = WIN_hwnd("Test DC")

Window Functions
WIN_GetClientArea( hwnd,@top,@left,@bottom,@right )
? top
? left
? bottom
? right
WIN_GetExStyle() : Retrieves the extended window styles.

Syntax
WIN_GetExtStyle( nHwnd )  nExtendedStyle
Parameters
Returns
nExtendedStyle extended style. If the function fails, the return value is set to zero.
Example
LOCAL hwnd
hwnd = WIN_hwnd( "Command" )
? WIN_GetExStyle( hwnd )
See also
WIN_GetHInstance() , WIN_GetStyle() , WIN_GetWndProc() , WIN_GetHwndParent()
WIN_GetForegroundWindow() : Returns a handle to the

foreground window (the window with which the user is
currently working).
Special
The system assigns a slightly higher priority to the thread that creates the foreground window than it does to other
threads
Syntax
WIN_GetForegroundWindow()  nHwnd
Parameters
None.
Returns
See also
WIN_SetForegroundWindow() .

Window Functions
WIN_GetHandle() : Retrieves a handle to the top-level window
corresponding to the passed parameter.
Remark
WIN_GetHandle() differs from WIN_hwnd() in the way both functions search for the window: WIN_GetHandle()
uses the FindWindow() Win32 API function while WIN_hwnd() uses the FoxPro API function (_WfindTitle() ).
Also WIN_GetHandle() can only retrieve top-level window handles.
Alias
WIN_GetHwnd()
Syntax
WIN_GetHandle( szTitle )  nHwnd
Parameters
szTitle title of the window that is to be found.
Returns
nHwnd window handle (HWND), or 0 if not found.
Example
LOCAL hwnd
hwnd = WIN_hwnd("Command")
? WIN_GetHInstance( hwnd )
See also
WIN_hwnd() .
WIN_GetHInstance() : Retrieves the handle of the application

instance that handles a given window.
Syntax
WIN_GetHInstance( nHwnd )  nInstance
Parameters
Returns
nInstance application instance. If the function fails, the return value is set to zero.
Example
LOCAL hwnd
hwnd = WIN_hwnd( "Command" )
? WIN_GetHInstance( hwnd )
See also
WIN_GetExStyle() , WIN_GetStyle() , WIN_GetWndProc() , WIN_GetHwndParent()

Window Functions
WIN_GetHwndParent() : Retrieves the handle of the parent
window, if any.
Syntax
WIN_GetHwndParent( nHwnd )  nHWndParent
Parameters
Returns
nHwndParent handle of the parent window, if any. If the function fails, the return value is set to zero.
Example
LOCAL hwnd
? WIN_GetHwndParent( hwnd )
See also
WIN_GetHInstance() , WIN_GetStyle() , WIN_GetExStyle() , WIN_GetHwndParent()
WIN_GetIcon() : Extracts a given icon from an executable or

DLL.
Syntax
WIN_GetIcon( szFile,nIndex )  nIcon
Parameters
szFile file to get an icon from.
nIndex icon index (starts with 0).
Returns
nIcon icon handle or 0 if error. Use WIN_DestroyIcon() to release the icon and to free all the
memory associated with it.
Example
LOCAL hwnd
LOCAL hdc
LOCAL hIcon
LOCAL szFile



Window Functions
WIN_getPort() : Returns the WHANDLE of the window that is
currently selected for user output.
Syntax
WIN_getPort()  nWHandle
Parameters
None.
Returns
nWHandle FoxPro window handle (WHANDLE).
Example
WIN_setPort(29431904) && This is Form1
? "WHANDLE is",WIN_getPort() && Display the value of WHANDLE in Form1

&& The switch will appear as two distinct elements ... first
&& words will appear on Form2, then the switch will take place,
&& then the rest will appear on Form1
? "Switching port",WIN_setPort(29431904),"at",TIME()

Window Functions
WIN_GetStyle() : Retrieves the window style.
Syntax
WIN_GetStyle( nHwnd )  nStyle
Parameters
nHwnd window handle (HWND). Identifies the window and, indirectly, the class to which the window
belongs.
Returns
nStyle style. If the function fails, the return value is set to zero.
Example
LOCAL hwnd
m.hwnd = WIN_hwnd("Command")
? WIN_GetStyle( m.hwnd )
See also
WIN_GetHInstance() , WIN_GetExStyle() , WIN_GetWndProc() , WIN_GetHwndParent()
WIN_GetWindowDC() : Retrieves the device context (DC) for

the entire window, including title bar, menus, and scroll
bars.
Special
A window device context permits painting anywhere in a window, because the origin of the device context is the
upper-left corner of the window instead of the client area.
After painting is complete, the WIN_ReleaseDC() function must be called to release the device context. Not
releasing the window device context has serious effects on painting requested by applications.
Syntax
WIN_GetWindowDC( nHwnd )  nDC
Parameters
Returns
nDC device context.
Example
LOCAL hwnd
LOCAL hdc
LOCAL hIcon
LOCAL szFile

Window Functions
WIN_GetWindows() : Retrieves all window handles obtained by

a call to WIN_EnumWindows().
Remark
The WIN_EnumWindows() function cannot act in one single shot. Internally, it provides Windows with an internal
FOCUS.FLL will be able to deliver all the window handles through its WIN_GetWindows() function. In very simple
WIN_EnumWindows() and then a call to WIN_GetWindows() .
Alias
GetWindows()
Syntax
WIN_GetWindows()  szWindows
Parameters
None.
Returns
szWindows a tokenized string with all window handles or an empty string ( "") if no top-level window is
found. Each token is separated from the other by a caret (^).
Example
LOCAL szWindows
LOCAL OldSep
LOCAL szTitle
LOCAL nTokens
LOCAL i
&& This example starts by enumerating all the top level windows.
IF ( WIN_EnumWindows() )
m.szWindows = WIN_GetWindows()
m.nTokens = STR_numtok( m.szWindows )
m.szHandle = STR_ntoken( i,m.szWindows )
m.szTitle = GetWindowTitle( VAL( m.szHandle ) )
IF ( ! EMPTY( m.szTitle ) )
? m.szTitle,m.szHandle
ENDIF
NEXT
ENDIF

Window Functions
WIN_GetWindowText() : Determines a window's title bar.
Special
If the specified window is a control, the text of the control is copied. However, WIN_GetWindowText() cannot
retrieve the text of a control in another application.
Syntax
WIN_GetWindowText( nHwnd )  szTitle
Parameters
Returns
Example
n = WIN_GetHandle( "Microsoft Word - FOCUS.FLL (1999).doc" )
? WIN_GetWindowText( n ) && "Microsoft Word - FOCUS.FLL (1999).doc"
WIN_GetWndProc() : Retrieves the address of the window

procedure, or a handle representing the address of the
window procedure.
Syntax
WIN_GetWndProc( nHwnd )  nWndProc
Parameters
Returns
nWndProc window procedure. If the function fails, the return value is set to zero.
Example
LOCAL hwnd
? WIN_GetWndProc( hwnd )
See also
WIN_handle() : Window handle (WHANDLE).

Special
WHANDLEs are not HWNDs !

Window Functions
Syntax
WIN_handle( szTitle )  nHandle
Parameters
szTitle title of the window of which we want to determine the handle.
Returns
nHandle window handle (WHANDLE).
See Also
WIN_hwnd() .
WIN_height() : Window height in pixels

Syntax
WIN_height( nWHandle )  nHeight
Parameters
Returns
nHeight height of window in pixels.
WIN_hwnd() : Returns the Windows HWND of a given window.

Special
Many Windows functions must operate on the Windows handle (HWND) of a window. Visual FoxPro works with different
handles: WHANDLE. The WIN_hwnd() function returns a value directly useful for Windows functions and not Visual
FoxPro functions. For example, if you want to obtain a device context on a specific form the WHANDLE value is of no
help at all: you must operate on the HWND value. Consequently, if you intend to use the WIN_GetWindowDC()
function you first need to obtain the HWND value of the window you want to work with.
WIN_GetHandle() differs from WIN_hwnd() in the way both functions search for the window: WIN_GetHandle()
uses the FindWindow() Win32 API function while WIN_hwnd() uses the FoxPro API function (_WfindTitle() ).
Also WIN_GetHandle() can only retrieve top-level window handles.
WHANDLEs are not HWNDs!
Syntax
WIN_hwnd( szTitle )  nHwnd
Parameters
szTitle window name (window title or form caption).
Returns
nHwnd window handle (HWND). 0 is returned for an invalid window handle.

Window Functions
See also
WIN_handle()
WIN_IsWindow() : Determines whether the specified window

handle identifies an existing window.
Alias
IsWindow()
Syntax
WIN_IsWindow( nHwnd )  lExist
Parameters
nHwnd window handle (HWND).None.
Returns
lExist if the window handle identifies an existing window, the return value is .T.; otherwise it is.F. .
WIN_IsWindowEnabled() : Determines whether the specified

window is enabled for mouse and keyboard input.
Alias
IsWindowEnabled()
Syntax
WIN_IsWindowEnabled( nHwnd )  lEnabled
Parameters
Returns
lEnabled if the window is enabled, the return value is .T. ; otherwise it is .F..
WIN_IsWindowUnicode() : Determines whether the specified

window is a native Unicode window.
Alias
IsWindowUnicode()
Syntax
WIN_IsWindowUnicode( nHwnd )  lUnicode
Parameters

Window Functions
Returns
lUnicode if the window is a native Unicode window, the return value is .T.; otherwise it is.F. .
WIN_IsWindowVisible() : Determines whether the specified

window is visible or not.
Alias
IsWindowVisible()
Syntax
WIN_IsWindowVisible( nHwnd )  lVisible
Parameters
Returns
lVisible if the window is visible on the screen, the return value is .T. ; otherwise it is .F. . The return
value may be .T. even if the window is totally overlapped by other windows.
WIN_LastVersion() : Returns the file stamp of WIN functions.

Remark
Syntax
WIN_LastVersion()  szLastVersion
Parameters
None.
Returns
"C:\Focus\5.0\WIN.C-Mon Oct 19 15:55:22 1998" .
WIN_left() : Window left border position in pixels.

Syntax
WIN_left( nWHandle )  nLeft
Parameters
Returns
nLeft window left border position in pixels.

Window Functions
WIN_Lock() : Disables or re-enables drawing in the specified
window.
Special
Only one window can be locked at a time. You can decide to lock a window at the early stages of Load() event and
unlock it at the as a final step in the Init() event. The dvlForm of FOCUS.VCX uses this mechanism to speed up
form loading.
Syntax
WIN_Lock( nHwnd )  lSuccess
Parameters
nHwnd window handle (HWND). Call WIN_lock(0) to unlock the window that's currently locked.
Returns
lSuccess .T. if the window was locked properly; .F. if not.
Example
&& Taken from the dvlForm Load() and Init() events :
PROCEDURE Load()
WITH This
IF ( .IsFocus() )
.hwnd = WIN_hwnd( This.caption )
IF ( .hwnd != 0 )
.IsLocked = WIN_Lock( .hwnd )
ENDIF
ENDIF
ENDWITH
ENDPROC
PROCEDURE Init()
WITH This
<tons of things to do>
IF ( .IsLocked ) && If the window was properly locked
WIN_Lock(0) && Unlock it now
ENDIF
ENDWITH
ENDPROC
WIN_main() : Desktop window handle (WHANDLE).

Special
WHANDLEs are not HWNDs ! The WIN_main() function is identical to WIN_handle( _SCREEN.caption ) . You
can obtain the HWND value of the handle by calling the WIN_WhandleToHwnd() function.
Syntax
WIN_main()  nHandle
Parameters
None.
Returns
nHandle main window handle (WHANDLE) : desktop.

Window Functions
WIN_MakeOval() : Creates an elliptical region and attach it to a
form.
Syntax
WIN_MakeOval( nHwnd )  lSuccess
Parameters
nHwnd Window handle (can be obtained by a call to WIN_hwnd() ).
Please remember that, when you do no need the elliptic region anymore, you MUST
release it with a call to the WIN_ClearOval() function.
Returns
lSuccess .T. if the elliptic region was successfully attached to the form; .F. if the function failed.
Example
LOCAL hWnd
WITH ThisForm

ENDIF
.Width = 324
.Height = 146
DODEFAULT()
WIN_MakeOval( m.hWnd )
ENDWITH

LOCAL hWnd
WIN_ClearOval( m.hWnd )
CLEAR EVENTS
The example of above creates the an elliptical form. The elliptical form is created in a similar way than the
GDI_CreateEllipticRegion() function but this time we use the WIN_MakeOval() function that is much simpler
to use. To beautify the presentation of the form, we have created a JPG file that fills perfectly the ellipse.

Window Functions
WIN_MsgBox() : Creates, displays, and operates a message
box.
Syntax
WIN_MsgBox( szText,nType,szTitle,nLanguageID )  nButton
Parameters
szText the message to be displayed.
nType specifies a set of bit flags that determine the contents and behavior of the dialog box. This
parameter can be a combination of flags from the following groups of flags :
Button Indication
Flag Value Meaning

MB_ABORTRETRYIGNORE 2 The message box contains three push
buttons: Abort, Retry, and Ignore.
MB_OK 0 The message box contains one push button:
OK. This is the default.
MB_OKCANCEL 1 The message box contains two push buttons:
OK and Cancel.
MB_RETRYCANCEL 5 The message box contains two push buttons:
Retry and Cancel.
MB_YESNO 4 The message box contains two push buttons:
Yes and No.
MB_YESNOCANCEL 3 The message box contains three push
buttons: Yes, No, and Cancel.
Icon Indication
Flag Value Meaning

MB_ICONEXCLAMATION, 48 An exclamation-point icon appears in the
MB_ICONWARNING message box.
MB_ICONINFORMATION, 64 A question-mark icon appears in the message
MB_ICONASTERISK box.
MB_ICONQUESTION 32 An icon consisting of a lowercase letter i in a
circle appears in the message box.
MB_ICONSTOP, 16 A stop-sign icon appears in the message box.
MB_ICONERROR,
MB_ICONHAND
Default Button
Flag Value Meaning

MB_DEFBUTTON1 0 The first button is the default button.
MB_DEFBUTTON1 is the default unless
MB_DEFBUTTON2 , MB_DEFBUTTON3 , or
MB_DEFBUTTON4 is specified.
MB_DEFBUTTON2 256 The second button is the default button.
MB_DEFBUTTON3 512 The third button is the default button.
MB_DEFBUTTON4 768 The fourth button is the default button.
Dialog Box Modality
Flag Value Meaning

MB_APPLMODAL 0 The user must respond to the message box
before continuing work in the current window.
However, the user can move to the windows
of other applications and work in those
windows. Depending on the hierarchy of
windows in the application, the user may be
able to move to other windows within the
application. All child windows of the parent of
the message box are automatically disabled,
but popup windows are not. MB_APPLMODAL
is the default if neither MB_SYSTEMMODAL nor

Window Functions
MB_TASKMODAL is specified.
MB_SYSTEMMODAL 4096 All applications are suspended until the user
responds to the message box. Unless the
application specifies MB_ICONHAND , the
message box does not become modal until
after it is created; consequently, the owner
window and other windows continue to receive
messages resulting from its activation. Use
system-modal message boxes to notify the
user of serious, potentially damaging errors
that require immediate attention (for
example, running out of memory).
MB_TASKMODAL 8192 Same as MB_APPLMODAL except that all the
top-level windows belonging to the current
task are disabled. Use this flag when you need
to prevent input to other windows in the
current application without suspending other
applications.
In addition, you can specify the following flags:
Flag Value Meaning

MB_DEFAULT_DESKTOP_ONLY 131072 The desktop currently receiving input must be
a default desktop; otherwise, the function
fails. A default desktop is one an application
runs on after the user has logged on.
MB_HELP 16384 Adds a Help button to the message box.
Choosing the Help button or pressing F1
generates a Help event.
MB_RIGHT 524288 The text is right-justified.
MB_RTLREADING 1048576 Displays message and caption text using
right-to-left reading order on Hebrew and
Arabic systems.
MB_SERVICE_NOTIFICATION 2097152 Windows NT only: The caller is a service
notifying the user of an event. The function
displays a message box on the current active
desktop, even if there is no user logged on to
the computer. If this flag is set, the hWnd
parameter must be NULL. This is so the
message box can appear on a desktop other
than the desktop corresponding to the hWnd.
MB_SETFOREGROUND 65536 The message box becomes the foreground
window. Internally, Windows calls the
SetForegroundWindow() function for the
message box.
MB_TOPMOST 262144 The message box is created with the
WS_EX_TOPMOST window style.
nLanguageID language ID:

0x0401 1025 Arabic
0x0403 1027 Catalan
0x0405 1029 Czech
0x0406 1030 Danish
0x0407 1031 German
0x0408 1032 Greek
0x040B 1035 Finnish
0x040C 1036 French

Window Functions
0x040D 1037 Hebrew
0x0410 1040 Italian
0x0412 1042 Korean
0x0413 1043 Dutch
0x0415 1045 Polish
0x0419 1049 Russian
0x041B 1051 Slovak
0x041D 1053 Swedish
0x041E 1054 Thai
0x041F 1055 Turkish
0x0420 1056 Urdu
0x0421 1057 Bahasa
Note that each localized release of Windows 95/98 and Windows NT/Windows 2000 typically
contains resources only for a limited set of languages. Thus, for example, the U.S. version offers
LANG_ENGLISH , the French version offers LANG_FRENCH , the German version offers
LANG_GERMAN , and the Japanese version offers LANG_JAPANESE . Each version offers
LANG_NEUTRAL . This limits the set of values that can be used with the nLanguageId
parameter. Before specifying a language identifier, you should enumerate the locales that are
installed on a system (LOC_EnumSystemLocales() and LOC_GetSystemLocales() of
FOCUS.FLL ).
Returns
nButton the return value of WIN_MsgBox() is identical to the standard MESSAGEBOX() function of
Visual FoxPro.
Example
#define DANISH 1030
? WIN_MsgBox( "The WIN_MsgBox() function creates, displays, and operates " + ;

"a message box. The message box contains an application-" + ;
"defined message and title...",69,"This is my Title",DANISH )
&& This produces the following display
WIN_raised() : Draws a raised edge of rectangle.

Special
WIN_raised() performs an internal call to the DrawEdge() Win32 API service. It does that by obtaining a device
context to the appropriate window (WIN_GetWindowDC() ). To obtain a device context, you first need to obtain the
HWND window handle thanks to WIN_hwnd() . Please remember that to each call to WIN_GetWindowDC() must
correspond a call to WIN_ReleaseDC() .

Window Functions
The sunken effect will disappear each time that Visual FoxPro repaints the window or the form which forces you to call
the WIN_raised() function (and possibly also the WIN_hwnd() , WIN_GetWindowDC() and WIN_ReleaseDC()
functions) each time the form is repainted (Paint() event).
Syntax
WIN_raised( nTop,nLeft,nBottom,nRight,nDC )  lSuccess
Parameters
nDC device context.
Returns
Example
LOCAL nDC && Device Context
DO FORM "testDC"
hwnd = WIN_hwnd( "Test DC" )

nDC = WIN_GetWindowDC( hwnd )
WIN_raised( 10,100,50,140,nDC )
WIN_ReleaseDC( hwnd,nDC )
WIN_raised() affects the whole window area, title included.
See also
WIN_sunken()
WIN_ReleaseDC() : Releases a device context (DC), freeing it

for use by other applications.
Special
A window device context permits painting anywhere in a window, because the origin of the device context is the
upper-left corner of the window instead of the client area.
To each call to WIN_GetWindowDC() must correspond a WIN_ReleaseDC() to release the device context. Not
releasing the window device context has serious effects on painting requested by applications.

Window Functions
Syntax
WIN_ReleaseDC( nHwnd,nDC )  lSuccess
Parameters
nDC device context.
Returns
WIN_right() : Window right border position in pixels.

Syntax
WIN_right( nWHandle )  nRight
Parameters
Returns
nRight window right border position in pixels.
WIN_Select() : Brings the specified window to the active

position on the screen.
Special
The output of Visual FoxPro is directed to the selected window.
Syntax
WIN_Select( szTitle )  lSuccess
Parameters
szTitle the title of the window that must be selected.
Returns
lSuccess .T. if the function is successful; .F. if not (no window has been found with that title).
Example
WIN_Select("Form1") && Select "Form1"
? TIME() && Display time
WIN_Select("Form2") && Select "Form2"
? TIME() && Display time
This example produces the following output with two forms that have been defined in VFP:

Window Functions
WIN_SetActiveWindow() : Redirects Windows output to the

window asociated with this handle (HWND).
Alias
SetActiveWindow()
See also
Remark
The WIN_SetActiveWindow() function activates a window, but not if the application is in the background. The
window will be brought into the foreground (top of Z order) if its application is in the foreground when the system
activates the window.
If the window identified by the nHwnd parameter was created by the calling thread, the active window status of the
calling thread is set to nHwnd . Otherwise, the active window status of the calling thread is set to NULL .
By using the AttachThreadInput() Win32 API function (not available in FOCUS.FLL ), a thread can attach its input
processing to another thread. This allows a thread to call WIN_SetActiveWindow() to activate a window attached
to another thread's message queue.
Syntax
WIN_SetActiveWindow( nHwnd )  nHwnd

Window Functions
Parameters
Returns
nHwnd if the function succeeds, the return value is the handle to the window that was previously
active. If the function fails, the return value is 0.
See also
WIN_SetFocusS(), WIN_SetFocus(), WIN_BringWindowToTop(), WIN_SetForegroundWindow()
WIN_SetFocus() : Sets the keyboard focus to the specified

window.
Special
All subsequent keyboard input is directed to this window. The window, if any, that previously had the keyboard focus
loses it.
Syntax
WIN_SetFocus( nHwnd )  nHwnd
Parameters
nHwnd handle of window to receive focus.
Returns
nHwnd If the function succeeds, the return value is the handle of the window that previously had the
keyboard focus. If there is no such window or if the nHwnd parameter is invalid, the return
value is 0.
See also
WIN_SetFocusS(), WIN_SetFocus(), WIN_BringWindowToTop(), WIN_SetForegroundWindow()
WIN_SetFocusS() : Shows a window and bring it on top.

Syntax
WIN_SetFocusS( szTitle )  nHwnd
Parameters
szTitle caption of the form to set focus to.
Returns
Example
DO FORM "frmTopLevel" && This form should be a top-level form
&& If the caption of this form is "TestFocus"
WIN_SetFocusS( "TestFocus" ) && This gives the focus to the form

Window Functions
See also
WIN_SetFocus(), WIN_SetActiveWindow(), WIN_BringWindowToTop(),
WIN_SetForegroundWindow()
WIN_SetForegroundWindow() : Puts the thread that created

the specified window into the foreground and activates
the window.
Remark
The WIN_SetForegroundWindow() function puts the thread that created the specified window into the foreground
and activates the window. Keyboard input is directed to the window, and various visual cues are changed for the user.
The system assigns a slightly higher priority to the thread that created the foreground window than it does to other
threads.
The foreground window is the window at the top of the Z order. It is the window that the user is working with. In a
preemptive multitasking environment, you should generally let the user control which window is the foreground
window.
Windows 98, Windows 2000: The system restricts which processes can set the foreground window. A process can
set the foreground window only if one of the following conditions is true:
 The process is the foreground process.
 The process was started by the foreground process.
 The process received the last input event.
 There is no foreground process.
 The foreground process is being debugged.
 The foreground lock time-out has expired.
 Windows 2000: No menus are active.

With this change, an application cannot force a window to the foreground while the user is working with another
window. Instead, WIN_SetForegroundWindow() will activate the window and call the FlashWindowEx() Win32
API function to notify the user.
Alias
SetForegroundWindow()
Syntax
WIN_SetForegroundWindow( nHwnd )  lSuccess
Parameters
Returns
lSuccess .T. if the window was brought to the foreground. If the window was not brought to the
foreground, the return value is .F. .
See also
WIN_SetFocus(), WIN_SetFocusS(), WIN_SetActiveWindow(), WIN_BringWindowToTop(),
WIN_GetForegroundWindow()

Window Functions
WIN_SetParent() : Changes the parent window of the specified
child window.
Syntax
WIN_SetParent( hwnd,hwndParent )  hwndOld
Parameters
hwnd handle to the child window.
hwndParent handle to the new parent window.
Returns
hwndOld handle to the previous parent window.
Example
LOCAL nHwndOld, nHwndNew, nHwndChild
m.nHwndChild = WIN_hwnd( This.caption )

m.nHWndNew = WIN_hwnd( "The new form" )
&& Change the parent window

m.nHWndNew = WIN_SetParent( m.nHwndChild,m.nHWndNew )
<do what you want>
&& Change the parent window to what it was

WIN_SetParent( m.nHwndChild,m.nHWndOld )
WIN_setPort() : Changes the user output window to be the

specified window.
Caution
WIN_setPort() will cause an API exception if you specify an invalid WHANDLE.
Syntax
WIN_setPort( nWHandle )  nWHandleOld
Parameters
nWHandle FoxPro window handle (WHANDLE).
Returns
nWHandleOld FoxPro window handle of the previous user output window (WHANDLE).
Example

&& The switch will appear as two distinct elements ... first
&& words will appear on Form2, then the switch will take place,
&& then the rest will appear on Form1
? "Switching port",WIN_setPort(29431904),"at",TIME()

Window Functions
WIN_sunken() : Draws a sunken edge of rectangle.

Special
WIN_sunken() performs an internal call to the DrawEdge() Win32 API service. It does that by obtaining a device
context to the appropriate window (WIN_GetWindowDC() ). To obtain a device context, you first need to obtain the
HWND window handle thanks to WIN_hwnd() . Please remember that to each call to WIN_GetWindowDC() must
correspond a call to WIN_ReleaseDC() .
The sunken effect will disappear each time that Visual FoxPro repaints the window or the form which forces you to call
the WIN_sunken() function (and possibly also the WIN_hwnd() , WIN_GetWindowDC() and WIN_ReleaseDC()
functions) each time the form is repainted (Paint() event).
Syntax
WIN_sunken( nTop,nLeft,nBottom,nRight,nDC )  lSuccess
Parameters

Window Functions
nDC device context.
Returns
Example
LOCAL nDC && Device Context
DO FORM "testDC"
hwnd = WIN_hwnd( "Test DC" )

nDC = WIN_GetWindowDC( hwnd )
WIN_sunken( 10,100,50,140,nDC )
WIN_ReleaseDC( hwnd,nDC )
WIN_sunken() affects the whole window area, title included.
See also
WIN_raised()
WIN_top() : Window top border position in pixels.

Syntax
WIN_top( nWHandle|szTitle )  nTop
Parameters
or…
Returns
nTop window top border position in pixels.
WIN_width() : Window width in pixels.

Syntax
WIN_width( nWHandle )  nWidth
Parameters

Window Functions
or…
Returns
nWidth window width in pixels.
WIN_WHandleToHwnd() : Returns the Windows HWND of the

specified WHANDLE.
Syntax
WIN_WandleToHwnd( nWHandle )  nHwnd
Parameters
Returns
nHwnd window handle( HWND).

ZIP Functions
ZIP Functions

ZIP Functions
Functions Synopsis
With version 8.05 of FOCUS.FLL , real ZIP functions have been incorporated in the
library. They are based on the fantastic work provided by zlib.
zlib was written by Jean-loup Gailly (compression) and Mark Adler (decompression).
Jean-loup is also the primary author/maintainer of gzip(1), the author of the
comp.compression FAQ list and the former maintainer of Info-ZIP's Zip; Mark is also
the author of gzip's and UnZip's main decompression routines and was the original
author of Zip. Not surprisingly, the compression algorithm used in zlib is essentially the
same as that in gzip and Zip, namely, the `deflate' method that originated in
PKWARE's PKZIP 2.x.
So far, only 2 functions have entered the world of FOCUS.FLL that provides a very
high level of abstraction to zlib, and hence to ZIP in general. You can expect more
functions in the future.
All the developers that would like to obtain further information about zlib can follow this URL:
http://www.gzip.org/zlib/.

ZIP Functions
MEM_Compress() : Compresses a string.

Syntax
MEM_Compress( szString )  szResult
Parameters
szString string to compress.
Returns
szResult the compressed string or an empty string in case of error (use ZIP_LastError() ).
Example
LOCAL szFile
LOCAL szOriginal
LOCAL szCompressed
LOCAL szDecompressed
m.szFile = GETFILE( "TXT" )
m.szOriginal = FILETOSTR( m.szFile )
IF ( ! EMPTY( m.szOriginal ) )
m.szCompressed = MEM_Compress( m.szOriginal )
IF ( ! EMPTY( m.szCompressed ) )
m.szDecompressed = MEM_Decompress( m.szCompressed )
IF ( ! EMPTY( m.szDecompressed ) )
IF ( m.szDecompressed == m.szOriginal )
? "Source and target are identical. This seems to be OK."
ELSE
? "Error in FOCUS.FLL: cannot retrieve original from compressed string"
ENDIF
ELSE
? "Error while decompressing",ZIP_LastError()
ENDIF
ELSE
? "Error while compressing",ZIP_LastError()
ENDIF
ELSE
? "File is empty"
ENDIF
ELSE
? "No file selected"

ENDIF

ZIP Functions
MEM_Decompress() : Decompresses a string compressed with
MEM_Compress().
Syntax
MEM_Decompress( szString )  szResult
Parameters
szString string to decompress.
Returns
szResult the decompressed string or an empty string in case of error (use ZIP_LastError() ).
Example
LOCAL szFile
LOCAL szOriginal
LOCAL szCompressed
LOCAL szDecompressed
m.szFile = GETFILE( "TXT" )
m.szOriginal = FILETOSTR( m.szFile )
IF ( ! EMPTY( m.szOriginal ) )
m.szCompressed = MEM_Compress( m.szOriginal )
IF ( ! EMPTY( m.szCompressed ) )
m.szDecompressed = MEM_Decompress( m.szCompressed )
IF ( ! EMPTY( m.szDecompressed ) )
IF ( m.szDecompressed == m.szOriginal )
? "Source and target are identical. This seems to be OK."
ELSE
? "Error in FOCUS.FLL: cannot retrieve original from compressed string"
ENDIF
ELSE
? "Error while decompressing",ZIP_LastError()
ENDIF
ELSE
? "Error while compressing",ZIP_LastError()
ENDIF
ELSE
? "File is empty"
ENDIF
ELSE
? "No file selected"

ENDIF

ZIP Functions
ZIP_Compress() : Compresses a set of files into a ZIP archive.
Syntax
So far, sub-directories cannot be included in the archive. It is also not possible to protect the archive by a
password. The level of compression is for now set to a default value that is compromise between the
maximum speed and the compression level.
Syntax
ZIP_Compress( szSkeleton,szZIP[,lAdd] )  nResult
Parameters
szSkeleton File skeleton so you can compress files that match a search criterion. Additional file skeletons
can be specified by cumulating them in a semicolon separated list ( ';').
szZIP the ZIP archive to create.
lAdd optional parameter; if specified and if evaluates to a logical true ( .T. ), then the files
corresponding to szSkeleton will be added to the ZIP archive and the original ZIP file won't
be recreated.
Returns
nResult 0 if success; otherwise browse through the following values:
Return Meaning
0 Success
-1 Cannot add a file to the archive. Call
ZIP_LastError() to obtain further
information about the error.
-2 Cannot create the ZIP archive.
-3 Cannot allocate memory.
-4 Compression aborted by callback.
3 Error while reading a file that must be add the
archive. Call ZIP_LastError() to obtain
further information about the error.
4 Error while writing a file that must be added the
5 Error while closing a file that must be added the
-4
Example
*** EXAMPLE #1 ***
LOCAL nError
m.nError = ZIP_Compress( "D:\MYDIR\*.*","D:\MYDIR\ALL.ZIP" )
IF ( m.nError != 0 )
? "Error while compressing files:",m.nError,ZIP_LastError()
ENDIF
&& Create a new archive file (ALL.ZIP) that will contain

&& all .doc files.
m.nError = ZIP_Compress( "D:\*.DOC","D:\ALL.ZIP" )
&& Update the archive file (ALL.ZIP) by adding
&& all .pdf files now.
m.nError = ZIP_Compress( "D:\*.PDF","D:\ALL.ZIP",.T. )
*** EXAMPLE #2 ***

ZIP_SetSubdirs( .F. ) && Don't include subdirs
IF ( ZIP_compress( "D:\xcase\*.*","d:\xcase1.zip" ) == 0 )
ZIP Functions
? FIL_size( "d:\xcase1.zip" ) && Display 19440063
ENDIF
*** EXAMPLE #3 ***

ZIP_SetSubdirs( .T. ) && Include subdirs
ENDIF
ZIP_Expand() : Expands all files contained in a ZIP archive.

Remark
So far, it is not possible to extract individual files from an archive. Archives that are protected by passwords
cannot be expanded.
Syntax
ZIP_Expand( szZIP,[szDir] )  nResult
Parameters
szZIP the ZIP archive to expand. All individual files will be recreated.
szDir directory where the files will be expanded.
Returns
nResult 0 if success; otherwise browse through the following values:
Return Meaning
0 Success
-100 Cannot locate a file in the archive.
-101 Cannot expand a file from the archive.
-102 Cannot set the current directory
-103 Cannot save current directory
-104 Cannot open archive.
-4 Expansion aborted by callback.
Example
LOCAL nError
&& If everything is correct

IF ( m.nError == 0 )
&& Simply recreate the files
m.nError = FIL_Expand( "D:\MYDIR\ALL.ZIP" )
? Error:",ZIP_LastError()
ENDIF
ENDIF
ZIP_LastError() : Determines the last error that occurred within

the ZIP_*() functions.
Syntax
ZIP_LastError()  szLastError
Parameters
None.

ZIP Functions
Returns
szLastError string describing the last error that occurred using the ZIP_*() functions.
Example
LOCAL nError
ENDIF
m.nError = ZIP_Compress( "D:\MYDIR\*.BMP;D:\MYDIR\*.HTM","D:\MYDIR\SOME.ZIP" )
ENDIF
ZIP_LastVersion() : Returns the source file stamp of ZIP

functions.
Remark
Syntax
ZIP_LastVersion()  szLastVersion
Parameters
None.
Returns
"D:\Focus\6.0\FWZip.c-Tue Apr 15 07:54:54 2003" .
ZIP_List() : List all files contained in a ZIP archive.

Syntax
ZIP_List( szZIP )  nEntries
Parameters
szZIP the ZIP archive to list. For each entry found in the ZIP file, the callback function set with
ZIP_SetCallback() is fired.
Returns
nEntries -1 in case of error; otherwise, the function returns the number of entries (files and directories)
found in the ZIP file.
Example
LOCAL szCallback
LOCAL szZIPFile
LOCAL nEntries

ZIP Functions
CLEAR
&& In this example, we will list through an archive file and display
&& each entry found thanks to the callback function.
m.szCallback = ZIP_SetCallback( "MyCallback()" )
m.szZIPFile = "D:\MANAGE2100\SENTANAI\PROJECTTRACKER.ZIP"
m.nEntries = ZIP_List( m.szZIPFile )
MESSAGEBOX( ALLTRIM(STR(m.nEntries)) + " entries were found in " + ;

m.szZIPFile,64,"FOCUS.FLL - ZIP_List()" )

ZIP_SetCallback( m.szCallback )
FUNCTION MyCallback( szOperation,szFile )

? m.szFile
RETURN ( .T. )
ZIP_SetCallback() : Gets/Sets a callback function for the

ZIP_Compress(), ZIP_Expand() and ZIP_List() functions.
Syntax
ZIP_SetCallback( [szFunc] )  szCurFunc
Parameters
szFunc the new callback function. This function should return a logical value, .T. or .F.. If it returns
.F., the current compression/expansion is aborted.
Returns
szCurFunc the current callback function.
Example
LOCAL szCallback
m.szCallback = ZIP_SetCallback( "MyCallback()" )
<... here you would have code that calls the ZIP_Compress() or ZIP_Expand() function >

ZIP_SetCallback( m.szCallback )
FUNCTION MyCallback( szOperation,szFile )

LOCAL lRetVal
&& Check if a file semaphore exists

&& If it exists, lRetVal is set to .F. (Stop Compress or Expansion)
&& Otherwise it is set to .T. (Continue Compress or Expansion)
m.lRetVal = ! FILE( "PLEASESTOP.SEM" )
RETURN ( m.lRetVal )
ZIP_SetSubdirs() : Gets/Sets the subdirectory flag as used in

ZIP_Compress().
Syntax
ZIP_SetSubdirs( [lSetting] )  lCurSetting

ZIP Functions
Parameters
lSetting optional parameter. If not passed, the function simply returns the current setting. .T. to
include subdirectories; .F. if not. By default, subdirectories are NOT compressed in
ZIP_Compress() .
Returns
lCurSetting the current internal setting as it is set in FOCUS.FLL , prior to call the function.
Example
ZIP_SetSubdirs( .F. ) && Don't include subdirs
ENDIF
ZIP_SetSubdirs( .T. ) && Include subdirs

ENDIF

Focus - FLL (2004)

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Focus - FLL (2004)

Încărcat de

Drepturi de autor:

Formate disponibile

FOCUS.

FOCUS.FLL Version 8.10

DATA DRIVEN APPLICATION FUNCTIONS...................................................................................................................................89

COMMON DIALOG FUNCTIONS...............................................................................................................................................104

FOCUS.FLL Version 8.10

FOCUS DATA FILE FUNCTIONS.............................................................................................................................................131

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

INI FILE FUNCTIONS..........................................................................................................................................................259

FOCUS.FLL Version 8.10

LANGUAGE SETTING FUNCTIONS............................................................................................................................................282

THE MESSAGING APPLICATION PROGRAM INTERFACE FOR C PROGRAMMERS......305

SIMPLE MAPI FUNCTIONS...................................................................................................................................................305

SIMPLE MAPI STRUCTURES..................................................................................................................................................305

SIMPLE MAPI C FUNCTIONS INSIGHT....................................................................................................................................306

FOCUS.FLL Version 8.10

BUILDING A KIND OF "MAPI .FLL" FOR FOXPRO.....................................................................................................................312

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

OBJECT ORIENTED FUNCTIONS..............................................................................................................................................434

FOCUS.FLL Version 8.10

REGULAR EXPRESSIONS FUNCTIONS.......................................................................................................................................467

FOCUS.FLL Version 8.10

SYSTEM PARAMETERS INFO FUNCTIONS..................................................................................................................................506

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

APPLICATION TRACING ORIENTED FUNCTIONS.........................................................................................................................674

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

Software License for FOCUS.FLL

End User License Agreement

FOCUS.FLL Version 8.10

Applicable law and venue

This agreement is governed by the laws of Belgium.

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

Most Common Questions

You need 2 dynamic link libraries:

3. FOCUS.EXE|KERNEL.EXE is not a valid Win32 application.

4. What are long function names?

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

Version Date Description of the Changes

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

7.97 20 November 2001 1. HTTP_GetCookie() : new function. No code impact.

8.0 1 September 2002 1. PRN_GetDefaultPrinter() : new function. No code impact.

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

8.07 27 February 2004 1. SCR_EnumDisplaySettings() : Enumerate the display settings of the

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

7.89 1. ADVAPI32.DLL 4.80.0.1675

7.90 1. ADVAPI32.DLL 4.80.0.1675

After Unchanged since version 7.90

FOCUS.FLL Version 8.10

FOCUS.FLL Version 8.10

ARR_average() : Returns the average of all numeric elements