Skip to content

Field Command

Obsolete

The Field command is obsolete. See the Struct command for creating and using structured types in DataFlex.

Be aware of existing code using Type. Type definitions convert signed values to unsigned; structs do not. This could impact your code after converting to structs, where signed values were previously converted.

See Also

Purpose

To name and assign a data type to a component of a data structure. This command is primarily used to define structures that are passed as parameters to DLLs.

Syntax

Type {type-name}
Field
    {field-name} As {data-type} [{count}]
:
End_Type

Argument Explanation

  • {type-name}: Is the name of the complex data type.
  • {field-name}: Is the name of the data-structure component.
  • {data-type}: Is the data type of the field. Below is a list of valid types and their respective byte sizes.
Type Size (bytes) Note
CHAR 1 Converted to Integer.
BYTE 1 Converted to Integer.
WORD 2 Converted to Integer.
SHORT 2 Converted to Integer.
DWORD 4
INTEGER 4
HANDLE 4
NUMBER 4 Converted to Integer.
DATE 4 Converted to Integer.
POINTER 4
STRING 4
  • {count}: If the field is to contain more than one instance of the data type, this argument may be used to specify how many.

What It Does

In DataFlex, a data structure is defined using the Type ... End_Type construction. The data structure is composed of one or more fields that are defined using the Field command to create each of these fields. The Field command specifies how many bytes are in the field and how its data will be interpreted by DataFlex.

The Field command creates a named part of a complex data structure for passing parameters to DLL procedures from DataFlex programs. Each field thus defined can be accessed using the GetBuff and Put commands.

Example

Below is an example of a simple type definition that defines RGB colors:

TYPE RGB
    Field Blue As CHAR
    Field Green As CHAR
    Field Red As CHAR
    Field Reserved As CHAR
END_TYPE

The following example shows how to use types with external functions. It is part of a serial communications class. The commDCB structure represents a communications device control block. It is used in the Win32 API, specifically with the BuildCommDCB and SetCommDCB functions. The contents of a commDCB are serial communications parameters.

```dataflex // Define 3 external functions we need to access the COM port. External_Function BuildCommDCB "BuildCommDCBA" Kernel32.DLL ; String sModeString Address pDCB returns Integer External_Function SetCommState "SetCommState" Kernel32.DLL HANDLE hComm Address pDCB Returns Integer External_Function CreateFile "CreateFileA" Kernel32.DLL String sPortName; DWORD dwRWOptions DWORD dwSharingOptions DWORD dwSecurityOptions; DWORD dwCreateOptions DWORD dwAttributes DWORD dwTemplate Returns Integer

// Some Win32 API Constants for CreateFile function.

Replace GENERIC_RW |CI$C0000000

ENUM_LIST // Create File creation options. Define CREATE_NEW FOR 1 Define CREATE_ALWAYS OPEN_EXISTING OPEN_ALWAYS TRUNCATE_EXISTING END_ENUM_LIST

Type commDCB // DataType used by SetCommState and BuildCommDCB Field cDCBLength As DWORD // Size of commDCB structure. Field cBaudRate As DWORD // Baud rate of port Field cfFlags As DWORD // 32 bits of flags Field cReserved As WORD // not used - do not use. Field cXonLim As WORD // Transmit X-ON threshold Field cXoffLim As WORD // Transmit X-OFF threshold Field cCHARSize As CHAR // Number of bits/CHAR, 4-8 Field cParity As CHAR // 0-4=None, Odd, Even, Mark, Space Field cStopBits As CHAR // 0, 1, 2 = 1, 1.5, 2 Field cXonChar As Char // Tx and Rx X-ON character Field cXoffChar As Char // Tx and Rx X-OFF character Field cPeChar As Char // Parity error replacement char Field cEofChar As Char // End of Input character Field cEvtChar As Char // Received Event character Field cReserved1 As WORD // not used - do not use. End_Type

Class cSimpleComm Is A Button Procedure Construct_Object Forward Send Construct_Object Property String psPortName Public "COM2:" // default "COM2:" Property String psParity Public "n" // default no-parity Property Integer piDataBits Public 8 // default 8 bits of data Property Integer piStopBits Public 1 // default 1 stop bit Property Integer piBaudRate Public 9600 // default 9600 baud rate Property HANDLE phComm Public 0 End_Procedure

// Build a Mode string that can be used with BuildCommDCB.
Function ModeString Returns String
    String sModeString
    Move (psPortName(Self) + " BAUD=" + String(piBaudRate(Self)) + ;
          " PARITY=" + psParity(Self) + " DATA=" + ;
          String(piDataBits(Self)) + " STOP=" + ;
          String(piStopBits(Self)) ) To sModeString
    Function_Return sModeString
End_Function

// Set up the Com port.
Function CommSetup Returns Integer
    String sCommDCB    // Buffer for accessing DCB.
    Pointer pCommDcb
    Integer iBaudRate  // For showing extraction.

    // Reset the structure. Fill it with nulls.
    // Note: The Type command automatically creates the _Size constant.
    // Its value is the size of the data structure in bytes.
    Move (Repeat(Character(0), commDCB_SIZE)) to sCommDCB

    // The commDCB structure requires the size as the first field.
    Put CommDCB_Size To sCommDCB At cDCBLength

    // Get a pointer to the DataFlex string.
    // Structures must be passed by pointer.
    GetAddress Of sCommDCB To pCommDCB

    // BuildCommDCB fills a CommDCB, based on a Mode command string.
    If (BuildCommDCB(ModeString(Self), pCommDCB)) Begin
        // Change the port settings.
        If (SetCommState(phComm(Self), pCommDCB)) Begin
            // Extract out the baud rate from the structure.
            // This just shows that extraction works too.
            Getbuff From sCommDCB At cBaudRate to iBaudRate
            Showln "The Baud Rate is " iBaudRate
            Function_Return TRUE
        End
    End
    Function_Return FALSE
End_Function

// Open the communication port.
Function OpenComm Returns Integer
    Integer hComm
    Move 0 to hComm
    Move (CreateFile(psPortName(Self), GENERIC_RW, 0, 0, ;
                      OPEN_EXISTING, 0, 0)) to hComm
    Set phComm to hComm
    Function_Return hComm
End_Function

End_Class

Object oTest Is A cSimpleComm Procedure OnClick If (OpenComm(Self)) Begin If (CommSetup(Self)) ; Send Stop_Box "Com settings changed!" "Success" Else ; Send Stop_Box ("Cannot Initialize Port " + (psPortName(Self))) "Failure" End Else ; Send Stop_Box ("Cannot open the communication port" + psPortName(Self)) "Failure" End_Procedure End_Object

Notes

  • The Field command may be used only in a Type ... End_Type structure-declaration block.
  • If you declare a structure, the size of the structure is automatically stored in a symbol called _Size.