Protheus Native Functions Reference

Quick reference for the most commonly used ADVPL/TLPP native functions in TOTVS Protheus.

String Functions

Alltrim

Removes leading and trailing spaces from a string.

Syntax: Alltrim( cString ) --> cTrimmed

Return: C - String without leading or trailing spaces.

Example:

Local cName := "  John Doe  "
cName := Alltrim(cName) // "John Doe"

SubStr

Extracts a substring from a string starting at a given position.

Syntax: SubStr( cString, nStart [, nCount] ) --> cSubString

Return: C - Extracted substring.

Example:

Local cText := "ADVPL Language"
Local cSub  := SubStr(cText, 1, 5) // "ADVPL"
Local cRest := SubStr(cText, 7)    // "Language"

StrTran

Replaces all occurrences of a substring within a string.

Syntax: StrTran( cString, cSearch [, cReplace [, nStart [, nCount]]] ) --> cResult

Return: C - String with replacements applied.

Example:

Local cText := "Hello World"
Local cCPF  := ""

cText := StrTran(cText, "World", "Protheus") // "Hello Protheus"
// Remove characters
cCPF := StrTran("123.456.789-00", ".", "")
cCPF := StrTran(cCPF, "-", "") // "12345678900"

PadR

Pads a value with trailing characters (default: spaces) to a specified length.

Syntax: PadR( xValue, nLength [, cFillChar] ) --> cPadded

Return: C - Right-padded string.

Example:

Local cCode := PadR("001", 6)        // "001   "
Local cFill := PadR("ABC", 6, "0")   // "ABC000"

PadL

Pads a value with leading characters (default: spaces) to a specified length.

Syntax: PadL( xValue, nLength [, cFillChar] ) --> cPadded

Return: C - Left-padded string.

Example:

Local cNum := PadL("42", 6)        // "    42"
Local cZero := PadL("42", 6, "0")  // "000042"

PadC

Centers a value within a string of the specified length.

Syntax: PadC( xValue, nLength [, cFillChar] ) --> cPadded

Return: C - Center-padded string.

Example:

Local cTitle := PadC("REPORT", 20) // "       REPORT       "

Upper

Converts all characters in a string to uppercase.

Syntax: Upper( cString ) --> cUpper

Return: C - Uppercase string.

Example:

Local cName := Upper("protheus") // "PROTHEUS"

Lower

Converts all characters in a string to lowercase.

Syntax: Lower( cString ) --> cLower

Return: C - Lowercase string.

Example:

Local cName := Lower("PROTHEUS") // "protheus"

Len

Returns the length of a string or array.

Syntax: Len( xValue ) --> nLength

Return: N - Number of characters in string or elements in array.

Example:

Local nLen := Len("ADVPL")  // 5
Local aArr := {1, 2, 3}
nLen := Len(aArr)            // 3

At

Returns the position of the first occurrence of a substring within a string.

Syntax: At( cSearch, cTarget [, nStart] ) --> nPosition

Return: N - Position of first occurrence, or 0 if not found.

Example:

Local nPos := At("World", "Hello World") // 7
Local nPos2 := At("xyz", "Hello World")  // 0

Rat

Returns the position of the last occurrence of a substring within a string.

Syntax: Rat( cSearch, cTarget ) --> nPosition

Return: N - Position of last occurrence, or 0 if not found.

Example:

Local cPath := "C:\TOTVS\bin\appserver.exe"
Local nPos := Rat("\", cPath) // Position of last backslash
Local cFile := SubStr(cPath, nPos + 1) // "appserver.exe"

Stuff

Deletes and/or inserts characters in a string at a specified position.

Syntax: Stuff( cString, nStart, nDelete, cInsert ) --> cResult

Return: C - Modified string.

Example:

Local cText := "Hello World"
cText := Stuff(cText, 6, 1, " Beautiful ") // "Hello Beautiful World"
// Replace portion
cText := Stuff("ABCDEF", 3, 2, "XY") // "ABXYEF"

Left

Returns a specified number of characters from the left side of a string.

Syntax: Left( cString, nCount ) --> cResult

Return: C - Leftmost characters.

Example:

Local cBranch := Left("01001", 2) // "01"

Right

Returns a specified number of characters from the right side of a string.

Syntax: Right( cString, nCount ) --> cResult

Return: C - Rightmost characters.

Example:

Local cExt := Right("report.pdf", 3) // "pdf"

Replicate

Returns a string repeated a specified number of times.

Syntax: Replicate( cString, nTimes ) --> cResult

Return: C - Repeated string.

Example:

Local cLine := Replicate("-", 40) // "----------------------------------------"

Space

Returns a string of spaces of the specified length.

Syntax: Space( nCount ) --> cSpaces

Return: C - String of spaces.

Example:

Local cField := Space(30) // Initializes a 30-character empty field

Transform

Formats a value according to a picture mask.

Syntax: Transform( xValue, cPicture ) --> cFormatted

Return: C - Formatted string.

Example:

Local cVal := Transform(1234.56, "@E 999,999.99")  // "  1.234,56"
Local cCPF := Transform("12345678900", "@R 999.999.999-99") // "123.456.789-00"

StrZero

Converts a number to a string with leading zeros.

Syntax: StrZero( nValue, nLength [, nDecimals] ) --> cResult

Return: C - Zero-padded numeric string.

Example:

Local cNum := StrZero(42, 6)   // "000042"
Local cDec := StrZero(3.5, 8, 2) // "00003.50"

CharRem

Removes specified characters from a string.

Syntax: CharRem( cCharsToRemove, cString ) --> cResult

Return: C - String with specified characters removed.

Example:

Local cClean := CharRem(".-/", "123.456.789-00") // "12345678900"

Asc

Returns the ASCII code of the first character of a string.

Syntax: Asc( cChar ) --> nAsciiCode

Return: N - ASCII code of the first character.

Example:

Local nCode := Asc("A") // 65
Local nCode2 := Asc("0") // 48

Chr

Returns the character corresponding to an ASCII code.

Syntax: Chr( nAsciiCode ) --> cChar

Return: C - Character for the given ASCII code.

Example:

Local cChar := Chr(65)  // "A"
Local cCRLF := Chr(13) + Chr(10) // Carriage return + line feed

Date/Time Functions

Date

Returns the current system date.

Syntax: Date() --> dToday

Return: D - Current system date.

Example:

Local dToday := Date()
Conout("Today is: " + DtoC(dToday))

dDataBase

Gets or sets the Protheus base date (reference date used in operations).

Syntax: dDataBase --> dDate (read) / dDataBase := dDate (write)

Return: D - Current base date.

Example:

// Get current database date
Local dRef := dDataBase

// Set base date
dDataBase := CtoD("01/01/2026")

DtoS

Converts a date to a string in the format YYYYMMDD.

Syntax: DtoS( dDate ) --> cDateString

Return: C - Date string in YYYYMMDD format.

Example:

Local cDate := DtoS(Date()) // "20260304"

StoD

Converts a string in YYYYMMDD format to a date value.

Syntax: StoD( cDateString ) --> dDate

Return: D - Date value.

Example:

Local dDate := StoD("20260304") // 2026-03-04

CtoD

Converts a string to a date using the current date format.

Syntax: CtoD( cDate ) --> dDate

Return: D - Date value.

Example:

Local dDate := CtoD("04/03/2026") // March 4, 2026 (DD/MM/YYYY)

DtoC

Converts a date to a character string using the current date format.

Syntax: DtoC( dDate ) --> cDate

Return: C - Date string in the current system format.

Example:

Local cDate := DtoC(Date()) // "04/03/2026" (in DD/MM/YYYY format)

Day

Returns the day of the month from a date.

Syntax: Day( dDate ) --> nDay

Return: N - Day of the month (1-31).

Example:

Local nDay := Day(Date()) // 4 (for March 4)

Month

Returns the month number from a date.

Syntax: Month( dDate ) --> nMonth

Return: N - Month number (1-12).

Example:

Local nMonth := Month(Date()) // 3 (for March)

Year

Returns the year from a date.

Syntax: Year( dDate ) --> nYear

Return: N - Four-digit year.

Example:

Local nYear := Year(Date()) // 2026

DOW

Returns the day of the week as a number.

Syntax: DOW( dDate ) --> nDayOfWeek

Return: N - Day of week (1=Sunday, 2=Monday, ..., 7=Saturday).

Example:

Local nDow := DOW(Date())
If nDow == 1 .Or. nDow == 7
    Conout("Weekend!")
EndIf

Time

Returns the current system time as a string.

Syntax: Time() --> cTime

Return: C - Time string in HH:MM:SS format.

Example:

Local cTime := Time() // "14:30:45"

ElapTime

Calculates the elapsed time between two time strings.

Syntax: ElapTime( cStartTime, cEndTime ) --> cElapsed

Return: C - Elapsed time in HH:MM:SS format.

Example:

Local cStart := "08:00:00"
Local cEnd   := "17:30:00"
Local cElap  := ElapTime(cStart, cEnd) // "09:30:00"

DaySub

Subtracts a number of days from a date.

Syntax: DaySub( dDate, nDays ) --> dResult

Return: D - Resulting date.

Example:

Local dYesterday := DaySub(Date(), 1)
Local dLastWeek  := DaySub(Date(), 7)

MonthSub

Subtracts a number of months from a date.

Syntax: MonthSub( dDate, nMonths ) --> dResult

Return: D - Resulting date.

Example:

Local dLastMonth := MonthSub(Date(), 1)
Local dLastYear  := MonthSub(Date(), 12)

DateValid

Validates whether a date is valid.

Syntax: DateValid( cDate ) --> lValid

Return: L - .T. if the date is valid, .F. otherwise.

Example:

If DateValid("29/02/2026")
    Conout("Valid date")
Else
    Conout("Invalid date") // 2026 is not a leap year
EndIf

Numeric Functions

Int

Returns the integer portion of a numeric value.

Syntax: Int( nValue ) --> nInteger

Return: N - Integer portion (truncated, not rounded).

Example:

Local nInt := Int(3.7)  // 3
Local nNeg := Int(-3.7) // -3

Round

Rounds a numeric value to a specified number of decimal places.

Syntax: Round( nValue, nDecimals ) --> nRounded

Return: N - Rounded value.

Example:

Local nVal := Round(3.456, 2)  // 3.46
Local nVal2 := Round(3.454, 2) // 3.45

Abs

Returns the absolute value of a number.

Syntax: Abs( nValue ) --> nAbsolute

Return: N - Absolute value.

Example:

Local nAbs := Abs(-42) // 42
Local nAbs2 := Abs(42) // 42

Val

Converts a character string to a numeric value.

Syntax: Val( cString ) --> nValue

Return: N - Numeric value.

Example:

Local nVal := Val("123.45") // 123.45
Local nVal2 := Val("42")    // 42

Str

Converts a numeric value to a character string.

Syntax: Str( nValue [, nLength [, nDecimals]] ) --> cString

Return: C - String representation of the number.

Example:

Local cNum := Str(42)        // "        42"
Local cDec := Str(3.14, 6, 2) // "  3.14"

NoRound

Truncates a numeric value to a specified number of decimal places without rounding.

Syntax: NoRound( nValue, nDecimals ) --> nTruncated

Return: N - Truncated value.

Example:

Local nVal := NoRound(3.456, 2) // 3.45 (not 3.46)
Local nVal2 := NoRound(9.999, 2) // 9.99

Mod

Returns the remainder of a division (modulo).

Syntax: Mod( nDividend, nDivisor ) --> nRemainder

Return: N - Remainder of the division.

Example:

Local nRem := Mod(10, 3) // 1
Local nEven := Mod(4, 2) // 0 (even number)

Log

Returns the natural logarithm (base e) of a number.

Syntax: Log( nValue ) --> nLog

Return: N - Natural logarithm.

Example:

Local nLog := Log(2.718281828) // ~1.0

Sqrt

Returns the square root of a number.

Syntax: Sqrt( nValue ) --> nSquareRoot

Return: N - Square root.

Example:

Local nSqrt := Sqrt(16) // 4
Local nSqrt2 := Sqrt(2) // 1.4142...

Max

Returns the larger of two numeric values.

Syntax: Max( nValue1, nValue2 ) --> nMax

Return: N - The larger value.

Example:

Local nMax := Max(10, 20) // 20

Min

Returns the smaller of two numeric values.

Syntax: Min( nValue1, nValue2 ) --> nMin

Return: N - The smaller value.

Example:

Local nMin := Min(10, 20) // 10

Array Functions

aAdd

Adds a new element to the end of an array.

Syntax: aAdd( aArray, xValue ) --> xValue

Return: U - The value added.

Example:

Local aList := {}
aAdd(aList, "Item 1")
aAdd(aList, "Item 2")
// aList == {"Item 1", "Item 2"}

aDel

Deletes an element from an array at a specified position. Does not resize the array.

Syntax: aDel( aArray, nPosition ) --> aArray

Return: A - The modified array (last element becomes NIL).

Example:

Local aList := {"A", "B", "C", "D"}
aDel(aList, 2)
// aList == {"A", "C", "D", NIL}
aSize(aList, 3) // Resize to remove NIL
// aList == {"A", "C", "D"}

aSize

Resizes an array to the specified number of elements.

Syntax: aSize( aArray, nNewSize ) --> aArray

Return: A - The resized array.

Example:

Local aList := {"A", "B", "C"}
aSize(aList, 5)  // aList == {"A", "B", "C", NIL, NIL}
aSize(aList, 2)  // aList == {"A", "B"}

aScan

Searches for a value in an array and returns its position.

Syntax: aScan( aArray, xSearch [, nStart [, nCount]] ) --> nPosition

Return: N - Position of the element, or 0 if not found.

Example:

Local aList := {"Apple", "Banana", "Cherry"}
Local nPos := aScan(aList, "Banana") // 2

// Using code block
Local aNums := {10, 25, 30, 45}
nPos := aScan(aNums, {|x| x > 20}) // 2 (first element > 20)

aSort

Sorts an array in ascending order.

Syntax: aSort( aArray [, nStart [, nCount [, bOrder]]] ) --> aArray

Return: A - The sorted array.

Example:

Local aList := {"Cherry", "Apple", "Banana"}
Local aNums := {3, 1, 4, 1, 5}

aSort(aList) // {"Apple", "Banana", "Cherry"}

// Descending order
aSort(aNums,,, {|x, y| x > y}) // {5, 4, 3, 1, 1}

aClone

Creates a deep copy of an array.

Syntax: aClone( aSource ) --> aNewArray

Return: A - New independent copy of the array.

Example:

Local aOrig := {"A", "B", "C"}
Local aCopy := aClone(aOrig)
aCopy[1] := "X"
// aOrig[1] is still "A"

Array

Creates a new array with a specified number of elements initialized to NIL.

Syntax: Array( nElements [, nElements2, ...] ) --> aArray

Return: A - New array.

Example:

Local aList := Array(5)       // {NIL, NIL, NIL, NIL, NIL}
Local aMatrix := Array(3, 2)  // 3x2 multidimensional array

aFill

Fills array elements with a specified value.

Syntax: aFill( aArray, xValue [, nStart [, nCount]] ) --> aArray

Return: A - The filled array.

Example:

Local aList := Array(5)
aFill(aList, 0) // {0, 0, 0, 0, 0}

aCopy

Copies elements from one array to another.

Syntax: aCopy( aSource, aTarget [, nStart [, nCount [, nTargetStart]]] ) --> aTarget

Return: A - The target array.

Example:

Local aSource := {1, 2, 3, 4, 5}
Local aTarget := Array(3)
aCopy(aSource, aTarget, 2, 3) // aTarget == {2, 3, 4}

aEval

Evaluates a code block for each element in an array.

Syntax: aEval( aArray, bBlock [, nStart [, nCount]] ) --> aArray

Return: A - The original array.

Example:

Local aNames := {"Alice", "Bob", "Charlie"}
aEval(aNames, {|cName, nIdx| Conout(Str(nIdx) + ": " + cName)})

aTail

Returns the last element of an array.

Syntax: aTail( aArray ) --> xValue

Return: U - The last element.

Example:

Local aList := {"First", "Second", "Last"}
Local cLast := aTail(aList) // "Last"

aIns

Inserts a NIL element at a specified position, shifting elements down.

Syntax: aIns( aArray, nPosition ) --> aArray

Return: A - The modified array (last element is lost).

Example:

Local aList := {"A", "B", "C", "D"}
aIns(aList, 2)
// aList == {"A", NIL, "B", "C"} - "D" is lost
aList[2] := "X"
// aList == {"A", "X", "B", "C"}

Database Functions

DbSelectArea

Selects a work area by alias name or number.

Syntax: DbSelectArea( xArea ) --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
DbSetOrder(1)
DbGoTop()

DbSetOrder

Sets the active index order for the current work area.

Syntax: DbSetOrder( nOrder ) --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
DbSetOrder(1) // Primary index: A1_FILIAL + A1_COD + A1_LOJA

DbSeek

Seeks a record by key in the current index order.

Syntax: DbSeek( xKey [, lSoftSeek [, lLast]] ) --> lFound

Return: L - .T. if record found, .F. otherwise.

Example:

DbSelectArea("SA1")
DbSetOrder(1)
If DbSeek(xFilial("SA1") + "000001" + "01")
    Conout("Customer found: " + SA1->A1_NOME)
Else
    Conout("Customer not found")
EndIf

DbSkip

Moves the record pointer forward or backward.

Syntax: DbSkip( [nRecords] ) --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
DbGoTop()
While !Eof()
    Conout(SA1->A1_NOME)
    DbSkip()
EndDo

DbGoTop

Moves the record pointer to the first record in the current work area.

Syntax: DbGoTop() --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
DbSetOrder(1)
DbGoTop()

DbGoBottom

Moves the record pointer to the last record in the current work area.

Syntax: DbGoBottom() --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
DbGoBottom()
Conout("Last record: " + Str(RecNo()))

RecLock

Locks the current record or adds a new record.

Syntax: RecLock( cAlias, lNewRecord ) --> lSuccess

Return: L - .T. if lock was successful.

Example:

// Update existing record
DbSelectArea("SA1")
DbSetOrder(1)
If DbSeek(xFilial("SA1") + "000001" + "01")
    If RecLock("SA1", .F.)
        SA1->A1_NOME := "New Name"
        MsUnlock()
    EndIf
EndIf

// Add new record
If RecLock("SA1", .T.)
    SA1->A1_FILIAL := xFilial("SA1")
    SA1->A1_COD    := "000100"
    SA1->A1_LOJA   := "01"
    SA1->A1_NOME   := "New Customer"
    MsUnlock()
EndIf

MsUnlock

Unlocks the current record after RecLock.

Syntax: MsUnlock() --> NIL

Return: NIL

Example:

If RecLock("SA1", .F.)
    SA1->A1_NOME := "Updated Name"
    MsUnlock()
EndIf

RecNo

Returns the current record number.

Syntax: RecNo() --> nRecNo

Return: N - Current record number.

Example:

DbSelectArea("SA1")
DbGoTop()
Conout("Record number: " + Str(RecNo()))

LastRec

Returns the total number of records in the current work area.

Syntax: LastRec() --> nLastRec

Return: N - Total number of records.

Example:

DbSelectArea("SA1")
Conout("Total records: " + Str(LastRec()))

Eof

Returns whether the record pointer is past the last record.

Syntax: Eof() --> lEof

Return: L - .T. if at end-of-file.

Example:

DbSelectArea("SA1")
DbGoTop()
While !Eof()
    // Process record
    DbSkip()
EndDo

Bof

Returns whether the record pointer is before the first record.

Syntax: Bof() --> lBof

Return: L - .T. if at beginning-of-file.

Example:

DbSelectArea("SA1")
DbGoBottom()
While !Bof()
    // Process record in reverse
    DbSkip(-1)
EndDo

Deleted

Returns whether the current record is marked for deletion.

Syntax: Deleted() --> lDeleted

Return: L - .T. if the record is deleted.

Example:

DbSelectArea("SA1")
DbGoTop()
If !Deleted()
    Conout("Active record: " + SA1->A1_NOME)
EndIf

DbSetFilter

Sets a filter condition on the current work area.

Syntax: DbSetFilter( bFilter [, cFilter] ) --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
DbSetFilter({|| SA1->A1_TIPO == "F"}, 'SA1->A1_TIPO == "F"')
DbGoTop()
While !Eof()
    Conout(SA1->A1_NOME) // Only physical person customers
    DbSkip()
EndDo
DbClearFilter()

IndexOrd

Returns the current index order number.

Syntax: IndexOrd() --> nOrder

Return: N - Current index order number.

Example:

DbSelectArea("SA1")
DbSetOrder(3)
Conout("Current index: " + Str(IndexOrd())) // 3

RetSqlName

Returns the physical SQL table name from the logical alias.

Syntax: RetSqlName( cAlias ) --> cTableName

Return: C - Physical SQL table name (e.g., "SA1010").

Example:

Local cTable := RetSqlName("SA1") // "SA1010" (depends on company/branch)
Local cQuery := "SELECT * FROM " + cTable + " WHERE D_E_L_E_T_ = ' '"

DbCloseArea

Closes the current work area.

Syntax: DbCloseArea() --> NIL

Return: NIL

Example:

DbSelectArea("SA1")
// ... work with data ...
DbCloseArea()

DbUseArea

Opens a table in a specified work area.

Syntax: DbUseArea( lNewArea, cDriver, cFile, cAlias, lShared, lReadOnly ) --> NIL

Return: NIL

Example:

DbUseArea(.T., "TOPCONN", RetSqlName("SA1"), "SA1_QRY", .T., .T.)

Alias

Returns the alias of the current or specified work area.

Syntax: Alias( [nWorkArea] ) --> cAlias

Return: C - Alias name, or empty string if work area is not in use.

Example:

DbSelectArea("SA1")
Conout(Alias()) // "SA1"

Select

Returns the work area number for a given alias.

Syntax: Select( [cAlias] ) --> nWorkArea

Return: N - Work area number, or 0 if not found.

Example:

Local nArea := Select("SA1")
If nArea > 0
    Conout("SA1 is open in work area: " + Str(nArea))
EndIf

Used

Returns whether the current work area has a table open.

Syntax: Used() --> lUsed

Return: L - .T. if a table is open in the current work area.

Example:

DbSelectArea("SA1")
If Used()
    Conout("SA1 is open")
EndIf

FCount

Returns the number of fields in the current work area.

Syntax: FCount() --> nFieldCount

Return: N - Number of fields.

Example:

DbSelectArea("SA1")
Conout("Number of fields: " + Str(FCount()))

FieldName

Returns the name of a field by its position number.

Syntax: FieldName( nPosition ) --> cFieldName

Return: C - Field name.

Example:

Local nI := 0

DbSelectArea("SA1")
For nI := 1 To FCount()
    Conout(FieldName(nI))
Next nI

FieldGet

Returns the value of a field by its position number.

Syntax: FieldGet( nPosition ) --> xValue

Return: U - Field value.

Example:

Local xVal := NIL

DbSelectArea("SA1")
DbGoTop()
xVal := FieldGet(1) // Value of first field

FieldPut

Sets the value of a field by its position number.

Syntax: FieldPut( nPosition, xValue ) --> xValue

Return: U - The value assigned.

Example:

DbSelectArea("SA1")
If RecLock("SA1", .F.)
    FieldPut(3, "New Value") // Sets the 3rd field
    MsUnlock()
EndIf

xFilial

Returns the branch code (filial) for a given alias, used in index key composition.

Syntax: xFilial( cAlias [, cFil] ) --> cRetFilial

Note: The second parameter cFil defaults to the system Private variable cFilAnt. Never use cFilial or cFilAnt as Local variable names — they are reserved by the framework.

Return: C - Branch code padded to the correct size.

Example:

DbSelectArea("SA1")
DbSetOrder(1)
// Seek using branch code
DbSeek(xFilial("SA1") + "000001" + "01")

Interface/UI Functions

MsgInfo

Displays an informational message dialog.

Syntax: MsgInfo( cMessage [, cTitle] ) --> NIL

Return: NIL

Example:

MsgInfo("Operation completed successfully!", "Success")

MsgYesNo

Displays a Yes/No confirmation dialog (Yes is the default).

Syntax: MsgYesNo( cMessage [, cTitle] ) --> lYes

Return: L - .T. if user clicked Yes, .F. if No.

Example:

If MsgYesNo("Do you want to continue?", "Confirmation")
    // User confirmed
    ProcessData()
EndIf

MsgAlert

Displays a warning/alert message dialog.

Syntax: MsgAlert( cMessage [, cTitle] ) --> NIL

Return: NIL

Example:

MsgAlert("Some fields are missing!", "Validation")

MsgStop

Displays an error/stop message dialog.

Syntax: MsgStop( cMessage [, cTitle] ) --> NIL

Return: NIL

Example:

MsgStop("Critical error: unable to save record.", "Error")

MsgNoYes

Displays a No/Yes confirmation dialog (No is the default).

Syntax: MsgNoYes( cMessage [, cTitle] ) --> lYes

Return: L - .T. if user clicked Yes, .F. if No.

Example:

If MsgNoYes("Are you sure you want to delete?", "Confirm Delete")
    DeleteRecord()
EndIf

FWExecView

Executes a standard CRUD view with an MVC model.

Syntax: FWExecView( cTitle, cSource, nOperation [, bOk [, bCancel [, nPercPosTela [, aEnableButtons]]]] ) --> nResult

Return: N - Operation result.

Example:

FWExecView("Customer Registration", "SA1", MODEL_OPERATION_INSERT)

Enchoice

Creates an automatic editing panel for Protheus standard screens.

Syntax: Enchoice( cAlias, nReg, nOpc [, aCRA [, cLetra [, cTexto [, aAcho [, aPos [, aTela [, nModelo]]]]]]] ) --> NIL

Return: NIL

Example:

Enchoice("SA1", 0, 3) // Opens insert form for SA1

MsDialog

Creates a standard Protheus dialog window.

Syntax: MsDialog():New( nTop, nLeft, nBottom, nRight, cTitle [, cStyle [, nClrText [, nClrBack [, oBrush [, oWnd [, lPixel [, oIcon]]]]]]] ) --> oDialog

Return: O - Dialog object.

Example:

Local oDlg
DEFINE MSDIALOG oDlg TITLE "My Dialog" FROM 0, 0 TO 300, 400 PIXEL
// Add controls here
ACTIVATE MSDIALOG oDlg CENTERED

MsGet

Creates an input field (GET) control.

Syntax: MsGet():New( nTop, nLeft, bSetGet, oWnd, nWidth, nHeight [, cPicture [, bValid [, nClrText [, nClrBack [, lPixel [, cF3]]]]]] ) --> oGet

Return: O - Get object.

Example:

Local cName := Space(30)
@ 10, 10 MSGET cName SIZE 100, 12 OF oDlg PIXEL

MsBrowse

Creates a data browse control for table navigation.

Syntax: MsBrowse():New( nTop, nLeft, nBottom, nRight, nStyle, bChange, oWnd [, aHeaders [, aColSizes [, aCols [, cAlias]]]] ) --> oBrowse

Return: O - Browse object.

Example:

Local oBrw
DbSelectArea("SA1")
DbSetOrder(1)
oBrw := MsBrowse():New(5, 5, 200, 350,, , oDlg,,,,,"SA1")

MsNewGetDados

Creates a grid control for detail data entry (used in master-detail screens).

Syntax: MsNewGetDados():New( nTop, nLeft, nBottom, nRight, nStyle, cLinOk, cTudoOk, cIniCpos, aAlter, nFreeze, nMax, cFieldOk, cSuperDel, cDelOk, oWnd, aHeader, aCols ) --> oGetDados

Return: O - GetDados grid object.

Example:

Local oGetD
Local aHeader := {}
Local aCols   := {}
// Build header and cols from SX3 definitions
oGetD := MsNewGetDados():New(60, 0, 200, 400,, "AllwaysTrue()", ;
    "AllwaysTrue()",, , 0, 99,,,, oDlg, aHeader, aCols)

Alert

Displays a simple alert message with optional button choices.

Syntax: Alert( cMessage [, aButtons] ) --> nChoice

Return: N - Number of the button pressed (1-based).

Example:

Local nOpt := Alert("Choose an option:", {"Save", "Cancel", "Help"})
If nOpt == 1
    // Save
EndIf

Pergunte

Loads and displays the parameter screen from SX1 dictionary.

Syntax: Pergunte( cGroup, lShowDialog [, cTitle] ) --> lConfirmed

Return: L - .T. if user confirmed, .F. if cancelled (always .T. when lShowDialog is .F.).

Example:

Local cFromDate := ""
Local cToDate   := ""

// Show parameter dialog for report filter
If Pergunte("MTR010", .T., "Sales Report Parameters")
    // Parameters are loaded into MV_PAR01, MV_PAR02, etc.
    cFromDate := MV_PAR01
    cToDate   := MV_PAR02
    RunReport(cFromDate, cToDate)
EndIf

// Load parameters silently (use last values)
Pergunte("MTR010", .F.)

File I/O Functions

FOpen

Opens a file for reading and/or writing.

Syntax: FOpen( cFileName [, nMode] ) --> nHandle

Return: N - File handle (>= 0 on success, -1 on failure).

Example:

Local nHandle := FOpen("C:\Temp\data.txt", 0) // Open for reading
If nHandle >= 0
    // Read file...
    FClose(nHandle)
Else
    Conout("Error opening file: " + Str(FError()))
EndIf

FRead

Reads data from an open file.

Syntax: FRead( nHandle, @cBuffer, nBytes ) --> nBytesRead

Return: N - Number of bytes actually read.

Example:

Local nHandle := FOpen("C:\Temp\data.txt", 0)
Local cBuffer := Space(1024)
Local nRead := FRead(nHandle, @cBuffer, 1024)
cBuffer := Left(cBuffer, nRead)
Conout(cBuffer)
FClose(nHandle)

FWrite

Writes data to an open file.

Syntax: FWrite( nHandle, cData [, nBytes] ) --> nBytesWritten

Return: N - Number of bytes actually written.

Example:

Local nHandle := FCreate("C:\Temp\output.txt")
FWrite(nHandle, "Line 1" + Chr(13) + Chr(10))
FWrite(nHandle, "Line 2" + Chr(13) + Chr(10))
FClose(nHandle)

FClose

Closes an open file.

Syntax: FClose( nHandle ) --> lSuccess

Return: L - .T. if closed successfully.

Example:

Local nHandle := FOpen("C:\Temp\data.txt")
// ... work with file ...
FClose(nHandle)

FErase

Deletes a file from the file system.

Syntax: FErase( cFileName ) --> nResult

Return: N - 0 on success, -1 on failure.

Example:

If FErase("C:\Temp\old_file.txt") == 0
    Conout("File deleted successfully")
EndIf

FRename

Renames a file.

Syntax: FRename( cOldName, cNewName ) --> nResult

Return: N - 0 on success, -1 on failure.

Example:

FRename("C:\Temp\old.txt", "C:\Temp\new.txt")

File

Checks if a file exists.

Syntax: File( cFileName ) --> lExists

Return: L - .T. if the file exists.

Example:

If File("C:\Temp\config.ini")
    Conout("Configuration file found")
EndIf

Directory

Returns an array with file and directory information.

Syntax: Directory( cPath [, cAttributes] ) --> aFiles

Return: A - Array of arrays: {cName, nSize, dDate, cTime, cAttributes}.

Example:

Local aFiles := Directory("C:\Temp\*.txt")
Local nI
For nI := 1 To Len(aFiles)
    Conout(aFiles[nI][1] + " - Size: " + Str(aFiles[nI][2]))
Next nI

MakeDir

Creates a new directory.

Syntax: MakeDir( cDirPath ) --> nResult

Return: N - 0 on success, -1 on failure.

Example:

If MakeDir("C:\Temp\Reports") == 0
    Conout("Directory created")
EndIf

CurDir

Returns the current directory.

Syntax: CurDir() --> cCurrentDir

Return: C - Current working directory path.

Example:

Local cDir := CurDir()
Conout("Current directory: " + cDir)

DirRemove

Removes an empty directory.

Syntax: DirRemove( cDirPath ) --> nResult

Return: N - 0 on success, -1 on failure.

Example:

If DirRemove("C:\Temp\OldReports") == 0
    Conout("Directory removed")
EndIf

FSeek

Moves the file pointer to a specified position.

Syntax: FSeek( nHandle, nOffset [, nOrigin] ) --> nPosition

Return: N - New file pointer position.

Example:

Local nHandle := FOpen("C:\Temp\data.bin", 0)
Local nSize := FSeek(nHandle, 0, 2) // Get file size by seeking to end
FSeek(nHandle, 0, 0)                // Return to beginning
Conout("File size: " + Str(nSize))
FClose(nHandle)

FCreate

Creates a new file or truncates an existing one.

Syntax: FCreate( cFileName [, nAttribute] ) --> nHandle

Return: N - File handle (>= 0 on success, -1 on failure).

Example:

Local nHandle := FCreate("C:\Temp\log.txt")
If nHandle >= 0
    FWrite(nHandle, "Log started at: " + Time() + Chr(13) + Chr(10))
    FClose(nHandle)
EndIf

System Functions

GetMV

Retrieves the value of an MV_* system parameter from SX6.

Syntax: GetMV( cParamName ) --> xValue

Return: U - Parameter value (type depends on parameter definition).

Example:

Local cState := GetMV("MV_ESTADO")
Conout("Default state: " + cState)

PutMV

Sets the value of an MV_* system parameter in SX6.

Syntax: PutMV( cParamName, xValue ) --> NIL

Return: NIL

Example:

PutMV("MV_ESTADO", "SP")

SuperGetMV

Retrieves the value of an MV_* parameter with default value support and caching.

Syntax: SuperGetMV( cParamName [, lHelp [, xDefault]] ) --> xValue

Return: U - Parameter value or default.

Example:

// Recommended over GetMV for better performance (uses cache)
Local nTaxRate := SuperGetMV("MV_TXICMS", .F., 18)
Local cCompany := SuperGetMV("MV_NOMEMP", .F., "My Company")

Conout

Outputs a message to the Protheus console log.

Syntax: Conout( cMessage [, cLogLevel] ) --> NIL

Return: NIL

Example:

Conout("Processing started at: " + Time())
Conout("Record count: " + Str(LastRec()))

FWLogMsg

Writes a message to the Protheus application log with level and context.

Syntax: FWLogMsg( cLevel, cGroup, cCategory, cSource, cDetail, cLogId, cMessage ) --> NIL

Return: NIL

Example:

FWLogMsg("ERROR", "FATURAMENTO", "NF", "MATA461", ;
    "Error generating invoice", "001", ;
    "Invoice generation failed for order " + cOrder)

GetEnvServer

Returns the name of the current Protheus environment.

Syntax: GetEnvServer() --> cEnvironment

Return: C - Current environment name.

Example:

Local cEnv := GetEnvServer()
Conout("Running in environment: " + cEnv) // e.g., "P12"

GetArea

Saves the current work area state (alias, order, record position).

Syntax: GetArea() --> aArea

Return: A - Array with the saved work area state.

Example:

// Always save and restore area when working with multiple tables
Local aArea := GetArea()

DbSelectArea("SA1")
DbSetOrder(1)
DbGoTop()
// ... process SA1 ...

RestArea(aArea)

RestArea

Restores a previously saved work area state.

Syntax: RestArea( aArea ) --> NIL

Return: NIL

Example:

Local aArea := GetArea()
// ... do work in other areas ...
RestArea(aArea) // Restores original area, order, and position

Type

Returns the data type of an expression given as a string.

Syntax: Type( cExpression ) --> cType

Return: C - Type character: "C", "N", "D", "L", "A", "O", "B", "U" (undefined/error).

Example:

Local cType := Type("SA1->A1_NOME") // "C"
If Type("cMyVar") != "U"
    Conout("Variable exists")
EndIf

ValType

Returns the data type of a value.

Syntax: ValType( xValue ) --> cType

Return: C - Type character: "C", "N", "D", "L", "A", "O", "B", "U".

Example:

Local xVar := "Hello"
Conout(ValType(xVar)) // "C"

xVar := 42
Conout(ValType(xVar)) // "N"

cValToChar

Converts any value to its character string representation.

Syntax: cValToChar( xValue ) --> cString

Return: C - String representation of the value.

Example:

Conout(cValToChar(42))        // "42"
Conout(cValToChar(.T.))       // ".T."
Conout(cValToChar(Date()))    // "04/03/2026"
Conout(cValToChar({"A","B"})) // "{...}"

Sleep

Pauses execution for a specified number of milliseconds.

Syntax: Sleep( nMilliseconds ) --> NIL

Return: NIL

Example:

Conout("Waiting 3 seconds...")
Sleep(3000)
Conout("Done!")

Seconds

Returns the number of seconds elapsed since midnight.

Syntax: Seconds() --> nSeconds

Return: N - Seconds since midnight (with fractional precision).

Example:

Local nStart := Seconds()
Local nEnd   := 0

// ... perform operation ...
nEnd := Seconds()
Conout("Elapsed: " + Str(nEnd - nStart, 10, 3) + " seconds")

GetNextAlias

Returns the next available alias name for temporary work areas.

Syntax: GetNextAlias() --> cAlias

Return: C - Available alias name (e.g., "QRY001").

Example:

Local cAlias := GetNextAlias()
DbUseArea(.T., "TOPCONN", RetSqlName("SA1"), cAlias, .T., .T.)
// ... use temporary alias ...
(cAlias)->(DbCloseArea())

FWFreeArray

Frees memory used by an array (sets elements to NIL and resizes to 0).

Syntax: FWFreeArray( aArray ) --> NIL

Return: NIL

Example:

Local aLargeData := {}
// ... populate with thousands of records ...
// Free memory when done
FWFreeArray(aLargeData)

ExistBlock

Checks if a code block (point of entry / user exit) exists.

Syntax: ExistBlock( cBlockName ) --> lExists

Return: L - .T. if the block exists in the RPO.

Example:

Local lOk := .T.

If ExistBlock("MT100LOK")
    lOk := ExecBlock("MT100LOK", .F., .F.)
EndIf

ExistFunc

Checks if a function exists in the compiled RPO.

Syntax: ExistFunc( cFuncName ) --> lExists

Return: L - .T. if the function exists.

Example:

If ExistFunc("MyCustomFunc")
    &("MyCustomFunc()")
EndIf

Company/Branch Management Functions (FW*)

CRITICAL: The Protheus framework maintains Private variables (cFilial, cFilAnt, cEmpAnt) for company/branch context. NEVER use these names as Local/Static variables — it shadows the system variables and causes data isolation bugs. Use cCodFil, cCodEmp instead. Always use the FW* functions below to read company/branch values.

FWCodFil

Returns the current branch code (M0_CODFIL).

Syntax: FWCodFil( [ cGrpCompany ] [, cEmpUDFil ] ) --> cCodFil

Return: C - Current branch code.

Example:

Local cCodFil := FWCodFil()
Conout("Branch code: " + cCodFil)

FWCodEmp

Returns the company code (or the company group if company is not configured in the group layout).

Syntax: FWCodEmp( [ cAlias ] ) --> cCodEmp

Return: C - Company code or company group.

Example:

Local cCodEmp := FWCodEmp()
Conout("Company: " + cCodEmp)

FWFilial

Returns the branch used by the system. When an alias is provided, returns the branch according to the table's sharing mode.

Syntax: FWFilial( [ cAlias ] ) --> cFil

Return: C - Branch code used by the system.

Example:

Local cFil := FWFilial("SA1")

FWCompany

Returns the company used by the system.

Syntax: FWCompany( [ cAlias ] ) --> cCompany

Return: C - Current company code.

Example:

Local cMyCompany := FWCompany()

FWGrpCompany

Returns the company group used by the system.

Syntax: FWGrpCompany() --> cGrpCompany

Return: C - Current company group.

Example:

Local cGrp := FWGrpCompany()

FWUnitBusiness

Returns the current business unit.

Syntax: FWUnitBusiness( [ cAlias ] ) --> cUnitBusiness

Return: C - Current business unit code.

Example:

Local cUnit := FWUnitBusiness()

FWAllCompany

Returns all companies for the given company group.

Syntax: FWAllCompany( [ cGrpCompany ] ) --> aAllCompany

Return: A - Array with all companies in the group.

Example:

Local aEmpresas := FWAllCompany()

FWAllFilial

Returns all branches for the given company group, company, and business unit.

Syntax: FWAllFilial( [ cCompany ] [, cUnitBusiness ] [, cGrpCompany ] [, lOnlyCode ] ) --> aAllFilial

Return: A - Array with all branches.

Example:

Local aFiliais := FWAllFilial()

FWAllGrpCompany

Returns all available company groups.

Syntax: FWAllGrpCompany() --> aAllGroup

Return: A - Array with all company groups.

Example:

Local aGrupos := FWAllGrpCompany()

FWSizeFilial

Returns the size of the branch field.

Syntax: FWSizeFilial( [ cGrpCompany ] ) --> nFilSize

Return: N - Branch field size.

Example:

Local nFilSize := FWSizeFilial()
Conout("Branch field size: " + cValToChar(nFilSize))

Transaction Functions

Begin Transaction

Starts a database transaction block. All operations within the block are atomic.

Syntax: BEGIN TRANSACTION

Example:

BEGIN TRANSACTION
    RecLock("SA1", .T.)
    SA1->A1_FILIAL := xFilial("SA1")
    SA1->A1_COD    := "000100"
    SA1->A1_LOJA   := "01"
    SA1->A1_NOME   := "Customer Name"
    MsUnlock()
END TRANSACTION

End Transaction

Ends a database transaction block, committing all changes.

Syntax: END TRANSACTION

Example:

BEGIN TRANSACTION
    // All database operations here are committed together
    RecLock("SC5", .F.)
    SC5->C5_NOTA := cInvoice
    MsUnlock()
END TRANSACTION

DisarmTransaction

Rolls back the current transaction, discarding all uncommitted changes.

Syntax: DisarmTransaction() --> NIL

Return: NIL

Example:

BEGIN TRANSACTION
    RecLock("SA1", .T.)
    SA1->A1_FILIAL := xFilial("SA1")
    SA1->A1_COD    := "000100"
    SA1->A1_NOME   := "Test"
    MsUnlock()

    If !ValidateData()
        DisarmTransaction() // Rolls back the insert
    EndIf
END TRANSACTION

TCSqlExec

Executes a SQL statement directly (INSERT, UPDATE, DELETE).

Syntax: TCSqlExec( cSql ) --> nResult

Return: N - 0 on success, negative on failure.

Example:

Local cSql := "UPDATE " + RetSqlName("SA1") + " SET A1_NOME = 'Updated' "
cSql += "WHERE A1_FILIAL = '" + xFilial("SA1") + "' "
cSql += "AND A1_COD = '000001' AND A1_LOJA = '01' "
cSql += "AND D_E_L_E_T_ = ' '"

If TCSqlExec(cSql) < 0
    Conout("SQL execution failed: " + TCSqlError())
EndIf

TCSetField

Sets the return field for a query opened with TCGenQry or embedded SQL.

Syntax: TCSetField( cAlias, cField, cType [, nSize [, nDecimals]] ) --> NIL