Functions and Directives

Function Set() Foundation

Changes and/or reads a system setting.

Syntax
Set( <nDefine>, [<xNewSetting>], [<lAdditive>] ) --> xOldSetting
Parameters
<nDefine>
<nDefine> is a positive integer identifying a system setting or system variable. In the header file "Set.ch" symbolic constants which are used to specify <nDefine> are defined.
<xNewSetting>
The optional expression <xNewSetting> can specify a new value for a system setting. The data type is dependent on the system setting designated by <nDefine>.
<lAdditive>
<lAdditive> is optional and only relates to the following system settings:
_SET_ALTFILE 
_SET_EXTRAFILE 
_SET_PRINTFILE 
When the value for <lAdditive> is .T. (true), the corresponding files are opened in append mode and new data is added to the end of the respective file. If the value is .F. (false) and the files already exist, they are first truncated to zero length before being opened. The default value is .T. (true).
Return

When Set() is called without the argument <xNewSetting>, the function returns the current system setting designated by <nDefine>. If <xNewSetting> is specified, the corresponding system setting is set to <xNewSetting> and the value of the old setting is returned.

Description

The environment function Set() reads and/or changes system settings or variables. The settings are identified by a numeric value which should always be specified as a symbolic constant. The symbolic constants are defined in the header file Set.ch. For almost every Set(<nDefine>) call there is a command or function which reads and/or changes only that single setting. Instead of Set(), the individual commands are preferred.

The following table lists the valid constants which can be used for <nDefine>. The accompanying data types for <xNewSetting> and the corresponding commands are listed next to each one. More exact information about the individual Set() settings can be found with the respective command or function. Set() does nothing when invalid values for <nDefine> or <xNewSetting> are passed to it.

The settings are grouped by scope, which is relevant when a program uses multiple threads. If settings with process-wide scope are changed in a thread, the new setting is valid for the entire process, or all threads. Settings with thread-local scope can be set individually for different threads. If a new thread is started, it inherits the thread-local settings from the thread it is started from. An exception is the SET CHARSET setting used for screen output. Character strings are always displayed according to the SET CHARSET setting of the main thread. String manipulation in memory, however, can be performed by two threads having different SET CHARSET settings.

Constants in Set.ch for Set() with process-wide scope
Constant Value data type Corresponding Command/Function
_SET_ALTERNATE L SET ALTERNATE
_SET_ALTFILE C SET ALTERNATE TO
_SET_BELL L SET BELL
_SET_CANCEL L SetCancel()
_SET_COLOR C SetColor()
_SET_CONFIRM L SET CONFIRM
_SET_CONSOLE L SET CONSOLE
_SET_CURSOR N SetCursor()
_SET_DELIMCHARS C SET DELIMITERS TO
_SET_DELIMITERS L SET DELIMITERS
_SET_DEVICE C SET DEVICE
_SET_DEVTIMEOUT N
_SET_ESCAPE L SET ESCAPE
_SET_EXIT L ReadExit()
_SET_EXTRA L
_SET_EXTRAFILE C
_SET_HANDLEEVENT L
_SET_INSERT L ReadInsert()
_SET_INTENSITY L SET INTENSITY
_SET_MARGIN N SET MARGIN
_SET_MCENTER L SET MESSAGE
_SET_MESSAGE N SET MESSAGE
_SET_PRINTER L SET PRINTER
_SET_PRINTFILE C SET PRINTER TO
_SET_SCOREBOARD L SET SCOREBOARD
_SET_TYPEAHEAD N SET TYPEAHEAD
_SET_WRAP L SET WRAP

Constants in Set.ch for Set() with thread-local scope
Constant Value data type Corresponding Command/Function
_SET_CHARSET N SET CHARSET
_SET_CENTURY L SET CENTURY
_SET_COLLATION L SET COLLATION
_SET_DATEFORMAT C SET DATE
_SET_DECIMALS N SET DECIMALS
_SET_DEFAULT C SET DEFAULT
_SET_DELETED L SET DELETED
_SET_EPOCH N SET EPOCH
_SET_EXACT L SET EXACT
_SET_EXCLUSIVE L SET EXCLUSIVE
_SET_FIXED L SET FIXED
_SET_HASH N SET HASH
_SET_LEXICAL L SET LEXICAL
_SET_OPTIMIZE L SET OPTIMIZE
_SET_PATH C SET PATH
_SET_RUSHMORE L SET RUSHMORE
_SET_SMARTFILTER L SET SMARTFILTER
_SET_SOFTSEEK L SET SOFTSEEK
_SET_TIME C SET TIME
_SET_UNIQUE L SET UNIQUE

_SET_COLLATION

Passing the constant _SET_COLLATION to the Set() function allows for the activatation of a pre-defined or user-defined collation table for modifying the sorting order of characters. The parameter <xNewSetting> is either a constant from the COLLAT.CH file, or a one dimensional array with 256 elements. The ASCII value of a character plus 1 defines the array element that contains the weighing factor for a character (see the third example).

_SET_DEVTIMEOUT

This setting is only recognized on Windows 95/98 platforms. It controls the timeout value in seconds for accessing a printer using text-mode printing routines (e.g. @...SAY, DevOut(), ?, ??). The default is 60 seconds. This is the maximum waiting period for the operating system to receive a printer response. If the printer does not respond within this time interval, a runtime error is raised. Note, however, that the timeout is independent of the printer status. If, for whatever reason, a printing operation cannot be completed within the timeout interval, a runtime error is raised even if the printer is printing or is ready to print. In addition, if an @...SAY command is directed to a printer, it may not return until the timeout has elapsed when the printer is not ready.

_SET_EXTRAFILE

No accompanying command exists for _SET_EXTRAFILE. This constant indicates an additional SET ALTERNATE file.

SET ALTERNATE TO <file> => _SET_ALTFILE    => _SET_EXTRAFILE 
SET ALTERNATE ON|OFF    => _SET_ALTERNATE  => _SET_EXTRA 

_SET_HASH

Set the default hash algorithm to be used by the function Char2Hash().

Set( _SET_HASH, 160 ) // Select the SHA1 algorithm 
Set( _SET_HASH, 256 ) // Select the SHA2-256 algorithm 
Set( _SET_HASH, 512 ) // Select the SHA3-512 algorithm 

_SET_HANDLEEVENT

This setting exists for compatibility reasons only. It allows for suppressing the automatic event handling while text-mode functions or commands like Achoice(), Memoedit(), GET/READ etc. are active. The setting defaults to .T. (true). When it is set to .F. (false), GUI controls mixed with text-mode controls will not respond to events while a text-mode function or command having an internal event handler is executed.

Examples
Save and set Set() settings

// The example sends data from a customer file to the 
// printer, and the output is diverted to a file. The output 
// channel (printer) as well as the output file are set by 
// Set(). The example further shows that Set() settings should 
// be saved when they are redefined and reset to the old 
// value before terminating a function/procedure. 

#include "Set.ch" 

PROCEDURE Main 
   LOCAL cPrintFile, lPrinterOn 

   cPrintFile := Set(_SET_PRINTFILE,"OUTPUT.TXT") 
   lPrinterOn := Set(_SET_PRINTER  , .T. ) 

   USE Customer NEW 
   DO WHILE ! Eof() 
      ? Lastname, Firstname 
      DbSkip() 
   ENDDO 

   Set(_SET_PRINTFILE, cPrintFile ) 
   Set(_SET_PRINTER  , lPrinterOn ) 

   USE 

RETURN 
Save and restore function for Set() settings

// This example does the same as the previous example 
/ "Saves and sets Set() settings", except that the values for 
// the Set() settings are programmed at the beginning in a 
// two-dimensional array. This array is passed to the function 
// ASet() where the new settings are set and the old are 
// saved in the array. Before termination of the procedure 
// Main, the old settings are reset when the array is 
// repassed to the function ASet(). 

#include "Set.ch" 

PROCEDURE Main 
   LOCAL aSets := { ; 
                    { _SET_PRINTFILE,"OUTPUT.TXT"}, ; 
                    { _SET_PRINTER  , .T.        }  ; 
                  } 

   ASet( aSets )          // Set/save Set() settings 

   USE Customer NEW 
   DO WHILE ! Eof() 
      ? Lastname, Firstname 
      DbSkip() 
   ENDDO 

   ASet( aSets )          // restore Set() settings 

   USE 
RETURN 

FUNCTION ASet( aSets ) 
RETURN AEval( aSets, {|a| a[2] := Set(a[1], a[2]) } ) 
Activate a user-defined collation table

// In the example, a case-insensitive collation table is activated 
// where umlauts are sorted in correct lexical order. 
// Strings can then be compared without using Upper() or Lower(). 

PROCEDURE Main 
   LOCAL aCollation[256] 
   LOCAL cUpperCase := "AÄBCDEFGHIJKLMNOÖPQRS TUÜVWXYZ" 
   LOCAL cLowerCase := "aäbcdefghijklmnoöpqrsßtuüvwxyz" 
   LOCAL nAscii, i, imax := Len( cLowerCase ), nSortOrder := 0 
   LOCAL aOldCollation 

   AFill( aCollation, 256 ) 

   // Upper and lower case letters receive identical weighing 
   // factors. The factors must be assigned to the array 
   // element nAscii+1 because ASCII codes start at 0 
   // and the array index starts with 1 
   FOR i:=1 TO imax 
      nAscii := Asc( SubStr( cUpperCase, i, 1 ) ) 
      IF nAscii <> 32 
         aCollation[ nAscii+1 ] := nSortOrder 
      ENDIF 
      nAscii := Asc( SubStr( cLowerCase, i, 1 ) ) 
      aCollation[ nAscii+1 ] := nSortOrder ++ 
   NEXT 

   // Sort all other characters after letters 
   i := 0 
   DO WHILE i < 256 .AND. ; 
          ( i := AScan( aCollation, 256, i+1 ) ) > 0 
      aCollation[ i ] := nSortOrder ++ 
   ENDDO 

   ? "lower" = "LOWER"              // Result: .F. 
   ? "UppER" = "uPPer"              // Result: .F. 
   ? "B"     < "Ä"                  // Result: .T. 

   aOldCollation := Set( _SET_COLLATION, aCollation ) 

   ? "lower" = "LOWER"              // Result: .T. 
   ? "UppER" = "uPPer"              // Result: .T. 
   ? "B"     < "Ä"                  // Result: .F. 

   Set( _SET_COLLATION, aOldCollation ) 
RETURN 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.