All structures used with 32-bit Windows API functions must be aligned on a 4 byte boundary. That is, pragma pack(4) must be called before typedef struct. Otherwise, structure data is not correctly
processed.
Info
See also: C Structure class,(struct),typedef struct Category: C Structure support,xHarbour extensions Header: cstruct.ch
LIB: xhb.lib
DLL: xhbdll.dll
PRIVATE
PRIVATE
Creates and optionally initializes a PRIVATE memory variable.
Syntax
PRIVATE <varName> [:= <xValue> ]
Arguments
PRIVATE <varName>
<varName> is the symbolic name of the PRIVATE variable to createe.
<xValue>
<xValue> is an optional value to assign to the PRIVATE variable after being created. To assign a value, the inline assignment operator (:=) must be used. The simple assignment operator (=) cannot be used.
Description
The PRIVATE statement creates a dynamic memory variable that has PRIVATE scope. Private variables are resolved at runtime, i.e. their symbolic name exist while a program is being executed.
This makes PRIVATE variables accessible for the Macro operator (&) at the expense of execution speed. The access to LOCAL variables is faster than to PRIVATE variables.
Private variables are visible from the time of creation until the declaring routine returns, or until they are explicitely released. Visibility of PRIVATEs extends to all subroutines called after variable creation. A private variable can become temporarily hidden when a subroutine declares a variable having the same symbolic name. This can lead to subtle programming error, so that the use of
PRIVATEs is discouraged unless there is good reason to use a PRIVATE variable. This is the case, for example, when it must be resolved within a macro expression.
It is possible to initialize a private variable already in the PRIVATE statement. To accomplish this, the inline-assignment operator must be used. The value of any valid expression can be assigned. This includes literal values and the return values of functions.
Note: PIVATE variables are declared with the MEMVAR statement and created with the PRIVATE statement. That means, PRIVATE is an executable statement that must follow all declaration
statements.
All undeclared variables that are assigned a value with the inline assignemnt operator, are created as PRIVATE variables.
Info
See also: FIELD,GLOBAL,LOCAL,MEMVAR,PUBLIC,RELEASE,STATIC Category: Declaration,Statements
Example
// These examples show different initializations of PRIVATE variables.
PROCDEURE Main
PRIVATE nNumber := 5 // initialized as numeric
PRIVATE
PRIVATE nAge, cName // uninitialized
dDate := Date() // undeclared but initialized RETURN
PROCEDURE
PROCEDURE
Declares a procedure along with its formal parameters.
Syntax
[STATIC] FUNCTION <funcName>( [<params,...>] ) [FIELD <fieldName,...> [IN <aliasName>]]
[MEMVAR <var_Dynamic,...>]
[LOCAL <var_Local> [:= <expression>] ,... ] [STATIC <var_Static> [:= <expression>] ,... ]
<Statements>
RETURN
Arguments
PROCEDUR <procName>( [<params,...>] )
This is the symbolic name of the declared procedure. It must begin with a letter or underscore followed by digits, letters or underscores. The symbolic name can contain up to 63 characters.
Optionally, the names of parameters <params,...> accepted by the procedure can be specified as a comma separated list. These parameters have LOCAL scope within the procedure.
When the procedure is declared as STATIC PROCEDURE, it is only visible within the PRG file that contains the procedure declaration and cannot be invoked from elsewhere.
FIELD <fieldName>
An optional list of field variables to use within the PROCEDURE can be declared with the FIELDstatement.
MEMVAR <var_Dynamic>
If dynamic memory variables, i.e. PRIVATE or PUBLIC variables, are used in the procedure, they are declared with theMEMVARstatement.
LOCAL <var_Local> [:= <expression>]
Local variables are declared and optionally initialized using theLOCALstatement.
STATIC <var_Static> [:= <expression>]
Static variables are declared and optionally initialized using theSTATICstatement.
RETURN
The RETURN statement terminates a procedure and branches control back to the calling routine.
A procedure has no return value.
Description
The PROCEDURE statement declares a procedure along with an optional list of parameters accepted by the function. Statements programmed in the procedure body form a self-contained part of a program that is executed when a procedure is called. Thus, tasks of a program can be split into several
procedures, each of which performs a sub-task when invoked.
PROCEDURE
The body of a procedure ends with the next FUNCTION, PROCEDURE or CLASS declaration, or at the end of file, which implies that procedure declarations cannot be nested.
The execution of a procedure ends when a RETURN statement is encountered in the procedure body.
A procedure does not return a value to the calling routine, only functions have a return value. The RETURN value is the only difference between functions and procedures.
When a procedure is declared with the STATIC modifier, its visibility is restricted to the PRG file that contains the STATIC PROCEDURE declaration. The names of STATIC procedures are resolved by the compiler and do not exist at runtime of a program. The names of non-STATIC procedures, also referred to as public procedures, are resolved by the linker and do exist at runtime. Thus, public procedures can be accessed by the Macro operator (&) while STATIC procedures cannot.
It is possible to declare STATIC procedures with the same symbolic name in different PRG files. A name conflict to a public procedure with the same name declared in another PRG file does not arise.
However, the symbolic names of public functions, procedures or classes must always be unique.
When a procedure is invoked with values being passed to it, they are assigned to the formal parameters declared with <params,...>. All variables declared in this list are LOCAL variables and their visibility is restricted to the statements programmed in the procedure body.
The number of values passed to a procedure does not need to match the number of parameters
declared. When fewer values are passed, the corresponding parameters are initialized with NIL. When more values are passed, the additional values are not asssigned to parameters but can be retrieved using function HB_AParams().
Info
See also: FIELD,FUNCTION,HB_AParams(),LOCAL,MEMVAR,METHOD (declaration), PARAMETERS,PCount(),PRIVATE,PUBLIC,RETURN,STATIC
Category: Declaration,Statements
Example
// The PROCEDURE statement is used in may other examples of // this documentation. See there.
PROTECTED:
PROTECTED:
Declares the PROTECTED attribute for a group of member variables and methods.
Syntax
PROTECTED:
Description
Protected member variables and methods are accessible in the class(es) declared in the PRG module and all subclasses. Subclasses are all classes that inherit directly or indirectly from the declared class.
A protected member is accessible within the context of a METHOD implemented in the declaring PRG module or in the PRG module of a subclass. Protected members are not accessible within the context of FUNCTION and PROCEDURE.
Info
See also: CLASS,DATA,EXPORTED:,HIDDEN:,METHOD (declaration) Category: Class declaration,Declaration,xHarbour extensions
Header: hbclass.ch Source: vm\classes.c
LIB: xhb.lib
DLL: xhbdll.dll
PUBLIC
PUBLIC
Creates and optionally initializes a PUBLIC memory variable.
Syntax
PUBLIC <varName> [:= <xValue> ]
Arguments
PUBLIC <varName>
<varName> is the symbolic name of the PUBLIC variable to createe.
<xValue>
<xValue> is an optional value to assign to the PUBLIC variable after being created. To assign a value, the inline assignment operator (:=) must be used. The simple assignment operator (=) cannot be used.
When a PUBLIC variable is not assigned a value upon creation, it is initialized with .F. (false).
This is different to all other variable types, which are initialized with NIL, by default.
Description
The PUBLIC statement creates a dynamic memory variable that has PUBLIC scope. Public variables are resolved at runtime, i.e. their symbolic name exist while a program is being executed. This makes PUBLIC variables accessible for the Macro operator (&) at the expense of execution speed. The access to GLOBAL variables is faster than to PUBLIC variables.
Public variables are visible from the time of creation until they are explicitely released. Visibility of PUBLICs extends to the entire program, even if a PUBLIC variable is created in a sub -routine which has returned. A public variable can become temporarily hidden when a subroutine declares a variable having the same symbolic name.
It is possible to initialize a public variable already in the PUBLIC statement. To accomplish this, the inline-assignment operator must be used. The value of any valid expression can be assigned. This includes literal values and the return values of functions.
Note: PUBLIC variables are declared with the MEMVAR statement and created with the PUBLIC statement. That means, PUBLIC is an executable statement that must follow all declaration statements.
Info
See also: FIELD,GLOBAL,LOCAL,MEMVAR,PRIVATE,RELEASE,STATIC Category: Declaration,Statements
Example
// This example creates PUBLIC variables in a sub-routine called from // the Main routine
PROCEDURE Main
? Type( "dataPath" ) // result: U
? Type( "tempPath" ) // result: U MakeConfig()
PUBLIC
? dataPath // result: C:\xhb\apps\data
? tempPath // result: C:\xhb\apps\temp RETURN
PROCEDURE MakeConfig()
PUBLIC dataPath := "C:\xhb\apps\data"
PUBLIC tempPath := "C:\xhb\apps\temp"
RETURN
REQUEST
REQUEST
Declares the symbolic name of an external function or procedure for the linker.
Syntax
REQUEST <name1> [,<nameN>]
Arguments
REQUEST <name>
This is the symbolic name of a function or procedure to declare for the linker. When multiple names are declared, they must be separated with commas.
Description
The REQUEST statement declares a symbolic name of a function or procedure for the linker. This is usually required when there is no direct call of a function or procedure in PRG code, for example when a function is only called within a macro-expression using the macro-operator. By requesting the symbolic name of a function, the linker is forced to link the c orresponding function to the executable file.
Info
See also: #include,EXTERNAL Category: Declaration
Example
// This example demonstrates a possible header file with some REQUEST // statements. The file can the be #included in PRG files that may // need the requested functions.
** File: Requests.ch REQUEST _ADS
REQUEST HBObject // EOF
RETURN
RETURN
Branches program control to the calling routine.
Syntax
RETURN [<retVal>]
Arguments
<retVal>
<retVal> is an expression of arbitrary data type that is passed from methods or functions to the calling routine. Procedures do not have a return value.
Description
The RETURN statement branches program control to the calling routine, eventually passing a value back. Before the called routine returns, all LOCAL and PRIVATE variables declared in this routine are discarded.
When the RETURN statement is executed by the main, or root, routine of an application, control goes back to the operating system.
Note: The RETURN statement is not the end of a FUNCTION or PROCEDURE declaration, it terminates execution of a called routine. It is possible to have multiple RETURN statements in the body of a FUNCTION or PROCEDURE declaration.
Info
See also: BEGIN SEQUENCE,ErrorLevel(),FUNCTION,LOCAL,PRIVATE,PROCEDURE, PUBLIC,QUIT
Category: Control structures,Statements
STATIC
STATIC
Declares and optionally initializes a STATIC memory variable.
Syntax
STATIC <varName> [:= <xValue> ]
Arguments
<varName>
<varName> is the symbolic name of the static variable to declare.
<xValue>
<xValue> is an optional value to assign to the STATIC variable after being declared. To assign a value, the inline assignment operator (:=) must be used. The simple assignment operator (=) cannot be used. Only literal values are allowed for <xValue> when declaring STATIC variables.
Description
The STATIC statement declares a memory variable that has STATIC scope. Static variables are resolved by the compiler, i.e. their symbolic name cannot be retrieved during runtime. This makes acces to STATIC variables much faster than to memory variables of PRIVATE or PUBLIC scope, whose symbolic variable names exist at runtime.
The names of STATIC variables cannot be included in macro-expressions since they cannot be resolved by the macro operator (&). This operator requires the symbolic name of a variable to exist at runtime.
The lifetime of STATIC variables is identical with the lifetime of a program. Unlike LOCAL variables, whose values are discarded when the declaring routine executes the RETURN statement, STATIC variables keep their values during the entire execution cycle of a program. The value assigned to a STATIC variable is stored in this variable until it gets assigned a new value.
The visibility of STATIC variables depends on the place of declaration:
1. When the STATIC declaration appears at the top of a PRG file before any other executable statement, the STATIC variable has file wide scope, i.e. it can be seen by all routines programmed in that PRG file.
2. When the STATIC declaration follows a FUNCTION, METHOD or PROCEDURE declaration, the variable can be seen only in the routine that declares the STATIC variable.
3. STATIC variables cannot be seen outside the PRG file that contains the STATIC declaration.
When a routine executes the RETURN statement, all STATIC variables declared in that routine keep their values.
The lines in PRG source code preceding the STATIC statement may not call executable code. They can only contain declaration statements, i.e. only the FUNCTION, METHOD, PROCEDURE statements, and the FIELD, LOCAL, MEMVAR or PARAMETERS variable declarations are allowed to precede the STATIC statement.
It is possible to initialize a static variable already in the STATIC statement. To accomplish this, the inline-assignment operator must be used. The values assigned to STATIC variables must be
programmed as literal values, i.e. the compiler must be able to resolve values assigned to STATIC
STATIC variables. It is not possible, for example, to initialize a STATIC variable with the RETURN value of a function, since this can only be resolved at runtime of a program.
Note: symbolic name as a STATIC variable, only the STATIC variable is visible. PRIVATE or PUBLIC variables with the same name become visible again, when the STATIC variable gets out of scope, i.e. when the routine that declares the STATIC variable returns or calls a subroutine.
Info
See also: FUNCTION,GLOBAL,LOCAL,PARAMETERS,PRIVATE,PROCEDURE,PUBLIC Category: Declaration,Statements
Example
// The example uses one PRIVATE variable and two STATIC variables to // demonstrate lifetime and visibility of STATIC variables.
STATIC snFileWide := 100 PROCEDURE Main
PRIVATE myVar := 10
? ProcName(), snFileWide, myVar // output: MAIN 100 10
Test1() // output: TEST1 100 3
Test2() // output: TEST2 110 12
? snFileWide // output: 120
? myVar // output: 12
RETURN
PROCEDURE Test1() STATIC myVar := 1
? ProcName(), snFileWide, myVar += 2 // output: TEST1 100 3 snFileWide += 10
RETURN
PROCEDURE Test2()
? ProcName(), snFileWide, myVar += 2 // output: TEST2 110 12 snFileWide += 10
RETURN
SWITCH
SWITCH
Executes one or more blocks of statements.
Syntax
The value of <Expression> must be of data type Character or Numeric. When it is of type Character, it must be a single character, not a character string. Numeric values must be integer values.
CASE <Constant1> .. <ConstantN>
<Constant> is a constant value of the same data type as <expression>. It must be a singlecharacter or an integer numeric value.
Description
The SWITCH statement compares a constant value against a series of constant values. It is similar to the DO CASE statement but outperforms it to a great extent due to the restrictions introduced with values permitted for comparison. As a general rule, only literal values in form of single characters or integer constants may follow the CASE clauses.
The SWITCH statement evaluates <Expression> and then searches for a first match between the resulting value and <Constant>. When a match is found, the statements following the corresponding CASE clause are executed down to the END statement. To suppress execution of statements of the next CASE clause, the EXIT statement must be explicitely used. This is a major difference to t he DO CASE statement where subsequent CASE clauses are skipped once a first match is found.
If no initial match is found with the CASE clauses, the statements following DEFAULT are executed, if present.
Info
See also: BEGIN SEQUENCE,DO CASE,FOR,FOR EACH,IF,TRY...CATCH Category: Control structures,Statements,xHarbour extensions
Examples
// The example demonstrates the SWITCH control structure with // EXIT statement
PROCEDURE Main
LOCAL nMonth := Month( Date() )
SWITCH
SWITCH nMonth CASE 1
CASE 2 CASE 3
? "First Quarter"
EXIT CASE 4 CASE 5 CASE 6
? "Second Quarter"
EXIT CASE 7 CASE 8 CASE 9
? "Third Quarter"
EXIT DEFAULT
? "Fourth quarter"
END RETURN
// The example demonstrates the SWITCH control structure without // EXIT statement
PROCEDURE Main
TRY...CATCH
TRY...CATCH
Declares a control structure for error handling.
Syntax
TRY
<statements>
[THROW( <oErrorObject> )]
[CATCH [<thrownError>]
<errorHandling>
[FINALLY
<guaranteed> ] END
Arguments
<statements>
These are the regular programming statements to execute in the TRY...CATCH control structure.
THROW <oErrorObject>
When an unexpected situation is detected in <statements>, a new Error object can be created explicitly and passed to theThrow()function. If <oErrorObject> is omitted and an error is detected by the xHarbour runtime, the Error object is created automatically.
CATCH <thrownError>
This is an optionally declared variable that receives the error object passed to the Throw() function in the TRY section of the control structure.
The statements following the CATCH clause are used for error handling.
FINALLY
The finally section is guaranteed to be executed, no matter if an error was handled or not.
Description
Any code that might throw an exception is placed inside of the try block. If an exception is thrown, the catch block is entered and the program can perform the appropriate operation to recover or alert the user.
If FINALLY is specified, code within the FINALLY section is guranteed to be executed after the TRY section has been executed and the CATCH section is activated, unless the CATCH section throws an UNHANDLED Error. This means that the FINALLY section will be executed even i f the CATCH section re-throws the error or attempts to RETURN. In such cases, the requested operation which forces out of the TRY section will be deferred until after the FINALLY section has been completed.
Important: although CATCH and FINALLY are both marked as optional, at least one of these options must be used within a TRY...END control block.
TRY...CATCH
Info
See also: BEGIN SEQUENCE,Error(),ErrorBlock(),ErrorNew(),Throw() Category: Control structures,Statements,xHarbour extensions
Example
// The example demonstrates program flow for a TRY..CATCH sequence PROCEDURE Main()
LOCAL oErr TRY
? "Trying"
? "Throwing"
Throw( ErrorNew( "Finalize Test", 0, 0, "Forced Error" ) ) CATCH oErr
? "Caught:", oErr:Operation
? "Throwing to outer, should be deferred"
Throw( oErr ) FINALLY
? "Finalized"
END
? "Oops, should have Re-Thrown, after the FINALLY."
RETURN