PBXA64 Inline Assembler Overview

PBXA64 Inline Assembler

The PBXA64 inline assembler provides full x86-64 assembly language support within PowerBASIC source files using the #ASM / #ENDASM directive pair. It supports over 1400 unique mnemonics across all major x86-64 ISA families, 21 operand kind variants, and 14 addressing modes.

Note: All mnemonics use Intel syntax (destination, source) order, consistent with MASM/TASM conventions.

Basic Syntax

FUNCTION PBMAIN() AS LONG
    #ASM
        mov eax, 42
        mov ebx, eax
        add ebx, 10
        mov [result], ebx
    #ENDASM
    PRINT result
END FUNCTION

Assembly blocks can appear at function scope or inside statement bodies. They are emitted directly into the function's code stream.

Variable Access with {name} Syntax

PB variables are accessed inside ASM blocks using curly brace notation. The assembler resolves the variable to its correct stack offset or global address and substitutes the effective address into the operand.

FUNCTION Demo() AS LONG
    LOCAL x AS LONG
    LOCAL y AS LONG
    LOCAL z AS LONG
    x = 10
    y = 20

    #ASM
        mov eax, DWORD PTR [{x}]   ; load x (stack offset)
        mov ecx, DWORD PTR [{y}]   ; load y
        add eax, ecx
        mov DWORD PTR [{z}], eax   ; store to z
    #ENDASM

    PRINT z   ; prints 30
END FUNCTION

Variable Access by Type

PB Declaration | ASM Access | Size
LOCAL n AS BYTE | BYTE PTR [{n}] | 1 byte
LOCAL n AS WORD | WORD PTR [{n}] | 2 bytes
LOCAL n AS DWORD | DWORD PTR [{n}] | 4 bytes
LOCAL n AS LONG | DWORD PTR [{n}] | 4 bytes
LOCAL n AS QUAD | QWORD PTR [{n}] | 8 bytes
LOCAL n AS INTEGER | WORD PTR [{n}] | 2 bytes
LOCAL n AS SINGLE | DWORD PTR [{n}] | 4 bytes (float)
LOCAL n AS DOUBLE | QWORD PTR [{n}] | 8 bytes (double)
LOCAL n AS STRING | QWORD PTR [{n}] | 8 bytes (data ptr)
LOCAL n AS STRING | QWORD PTR [LEN({n})] | 8 bytes (length)
LOCAL n AS STRING | QWORD PTR [STRPTR({n})] | 8 bytes (data ptr)

ASM Macros

The assembler provides built-in macros for PowerBASIC variable introspection:

Macro | Description
LEN(variable) | Resolves to the length field offset of a string variable
STRPTR(variable) | Resolves to the data pointer of a string variable
VARPTR(variable) | Resolves to the address/offset of any variable
SIZEOF(variable) | Resolves to the compile-time size of a variable or type

Segment Overrides

The assembler supports segment overrides for thread-local storage and system operations:

Override | Purpose | Example
fs: | Windows TEB (Thread Environment Block) | mov rax, QWORD PTR fs:[0x30]
gs: | Windows PEB / x64 TLS base | mov rax, gs:[0x60]

Addressing Modes

The assembler supports 6 primary addressing modes with 21 operand kind variants:

  1. Register — mov eax, ebx
  2. Immediate — mov eax, 42
  3. Direct memory — mov eax, [12345678h]
  4. Base + displacement — mov eax, [rbp-8]
  5. Base + index — mov eax, [rbx+rcx]
  6. Base + index*scale + displacement — mov eax, [rbx+rcx*4+16]
  7. RIP-relative — mov eax, [rip+label]

See Addressing Modes Reference for full details.

Supported ISA Families

ISA Family | Mnemonics | Reference
x86-64 Core (GPR) | ~400 | Core Mnemonics
SSE/SSE2/SSE3/SSSE3/SSE4 | ~300 | SSE Mnemonics
AVX/AVX2/AVX-512/FMA | ~500 | AVX Mnemonics
BMI1/BMI2 | ~16 | BMI Mnemonics
AES-NI / SHA / CLMUL / CRC32 / GFNI | ~30 | Crypto Mnemonics
System Instructions | ~50 | System Mnemonics
SGX / VMX / CET | ~50 | SGX/VMX/CET
MMX | ~60 | MMX Mnemonics
x87 FPU | ~80 | FPU Mnemonics
Cache Control | ~20 | Cache Mnemonics

Directives

The assembler supports a variety of directives for alignment, zero-initialization, and structured exception handling (SEH). See Directives Reference for full details.

Compiler Version

This reference applies to PBXA64 V32+ (May 2026). The assembler engine supports over 1500 unique mnemonics across all ISA families, verified by runtime test suite.


Assembler Directives

PBXA64's assembler supports a set of directives for controlling alignment, data emission, and structured exception handling (SEH) unwind information. Directives are used inside #ASM / #ENDASM blocks.

Alignment Directives

#ALIGN

Controls struct member alignment within PB TYPE / UNION blocks. Also controls overall section alignment in assembly blocks.

#ALIGN 16       ' align to 16-byte boundary

When used inside a TYPE/UNION context, #ALIGN controls the packing alignment of subsequent members. The default alignment is the natural alignment of each member type.

.p2align

Pad the current section with NOP instructions to achieve the specified alignment boundary. The directive takes a power-of-two exponent.

#ASM
    .p2align 4      ; align to 16-byte boundary (2^4)
    .p2align 5, 0x90, 8  ; align to 32-byte, pad with NOPs, max 8 bytes
#ENDASM

Parameters:

Parameter | Description
align | Power-of-two alignment (e.g., 4 = 16 bytes, 5 = 32 bytes)
fill | Optional fill byte (default: 0x90 = NOP)
max | Optional maximum bytes to insert

.zero

Emit a block of zero-initialized memory. Commonly used for alignment padding or data reservation.

#ASM
    .zero 32        ; emit 32 zero bytes
#ENDASM

SEH (Structured Exception Handling) Directives

These directives emit unwind information into the .pdata and .xdata PE sections, enabling the Windows x64 exception handler to unwind the stack correctly.

.seh_proc

Marks the beginning of a function with SEH unwind information. Required before any other SEH directives.

.seh_proc MyFunction

.seh_endprologue

Marks the end of the function prologue. After this point, the stack frame is fully set up and unwind codes have been recorded.

.seh_endprologue

.seh_pushreg

Records that a non-volatile register was pushed onto the stack. The register is restored during unwinding.

.seh_pushreg rbx
.seh_pushreg rsi
.seh_pushreg rdi

.seh_setframe

Establishes a frame pointer register with optional scaled offset. The frame pointer is used to access local variables and parameters during unwinding.

.seh_setframe rbp, 0   ; rbp is frame pointer, no scaled offset

.seh_stackalloc

Records that a specified number of bytes were allocated on the stack (typically via sub rsp, X).

.seh_stackalloc 64    ; 64 bytes of local stack allocated

.seh_savereg

Records that a non-volatile register was saved to a specific stack offset from the frame pointer or stack pointer.

.seh_savereg rbx, 32   ; rbx saved at [rbp+32] or [rsp+32]

.seh_savexmm

Records that a non-volatile XMM register was saved to a specific stack offset.

.seh_savexmm xmm6, 16  ; xmm6 saved at [rbp+16]

.seh_pushframe

Records that a frame was pushed (used for exception handling chain frames). The optional [code] flag indicates if a return address was pushed.

.seh_pushframe         ; push frame without return address
.seh_pushframe code     ; push frame with return address on stack

.seh_handler

Associates an exception handler function with the current procedure. Used for TRY/CATCH/FINALLY support.

.seh_handler ExceptionHandler, @except
.seh_handler FinallyHandler, @finally

.seh_endproc

Marks the end of a function's SEH unwind information. Must appear after all other SEH directives for the function.

.seh_endproc

Complete SEH Example

; Standard x64 function prologue with SEH
#ASM
.seh_proc MyFunc
    push rbp
    .seh_pushreg rbp
    mov rbp, rsp
    .seh_setframe rbp, 0
    sub rsp, 48
    .seh_stackalloc 48
    .seh_endprologue

    ; function body
    mov DWORD PTR [rbp-4], 42
    mov eax, DWORD PTR [rbp-4]

    ; epilogue
    add rsp, 48
    pop rbp
    ret
.seh_endproc
#ENDASM

Emit Directives

.byte

Emit raw byte values into the code stream.

.byte 0x90, 0x90, 0xCC    ; NOP, NOP, INT3

.word

Emit 16-bit word values.

.word 0x1234, 0x5678

.long

Emit 32-bit long values.

.long 0x12345678

.quad

Emit 64-bit quadword values.

.quad 0x1234567890ABCDEF

Section Directives

.section

Switch to a named section. Standard sections include .text, .data, .bss, .rdata.

.section .data
.section .rdata, "rd"   ; read-only data section

.section .text
    ; code follows

.text / .data / .bss

Convenience aliases for common sections.

.data
myVar: .quad 42

.text
    mov rax, QWORD PTR [myVar]


Addressing Modes Reference

The PBXA64 assembler supports 7 primary addressing modes with 21 operand kind variants across 14 encoding forms. All addressing modes follow Intel syntax (destination, source order).

Addressing Mode Summary

# | Mode | Syntax | Encoding | Example
1 | Register | reg | ModRM.reg / ModRM.rm | mov eax, ebx
2 | Immediate | imm | Immediate field | mov eax, 42
3 | Direct memory | [addr] | ModRM: 00 000 101 + disp32 | mov eax, [12345678h]
4 | Base+disp8 | [reg+disp8] | ModRM: 01 xxx xxx + disp8 | mov eax, [rcx+8]
5 | Base+disp32 | [reg+disp32] | ModRM: 10 xxx xxx + disp32 | mov eax, [rcx+1024]
6 | Base+index | [base+index] | ModRM+SIB: 00 100 xxx | mov eax, [rbx+rcx]
7 | Base+index+disp8 | [base+index+disp8] | ModRM+SIB: 01 100 xxx | mov eax, [rbx+rcx+8]
8 | Base+index+disp32 | [base+index+disp32] | ModRM+SIB: 10 100 xxx | mov eax, [rbx+rcx+1024]
9 | Index*scale | [index*scale] | ModRM+SIB: 00 100 101 | mov eax, [rcx*4]
10 | Index*scale+disp32 | [index*scale+disp] | ModRM+SIB: 00 100 101 + disp32 | mov eax, [rcx*4+16]
11 | Base+index*scale | [base+index*scale] | ModRM+SIB: scale=index | mov eax, [rbx+rcx*4]
12 | Base+index*scale+disp8 | [base+index*scale+disp8] | ModRM+SIB: 01 xxx xxx | mov eax, [rbx+rcx*4+8]
13 | Base+index*scale+disp32 | [base+index*scale+disp32] | ModRM+SIB: 10 xxx xxx | mov eax, [rbx+rcx*4+1024]
14 | RIP-relative | [rip+disp] | ModRM: 00 000 101 + disp32 (relative) | mov rax, [rip+label]
15 | RIP-relative+index | [rip+index*scale+disp] | RIP+SIB | mov rax, [rip+rcx*4+label]
16 | FS-segment override | fs:[base+disp] | Segment prefix 64h + ModRM | mov rax, fs:[0x30]
17 | GS-segment override | gs:[base+disp] | Segment prefix 65h + ModRM | mov rax, gs:[0x60]
18 | FS+RIP-relative | fs:[rip+disp] | 64h + RIP-relative | mov rax, fs:[rip+label]
19 | GS+RIP-relative | gs:[rip+disp] | 65h + RIP-relative | mov rax, gs:[rip+tls_var]
20 | Register (implicit) | reg | Opcode bits | push rbx (opcode 53h)
21 | Immediate (implied) | imm | Implicit in opcode | ret 16 (imm16 in opcode C2h)

1. Register Addressing

The operand is a register. The register is encoded in the ModRM byte or in the primary opcode.

mov eax, ebx        ; eax = ebx
add rcx, rdx        ; rcx = rcx + rdx
xor r8d, r9d        ; r8d = r8d xor r9d

2. Immediate Addressing

The operand is a constant value embedded in the instruction. The immediate size depends on the operand size.

mov eax, 42         ; 32-bit immediate
mov rax, 0x12345678 ; 32-bit sign-extended immediate
mov rcx, -1         ; sign-extended immediate
add ebx, 256        ; 32-bit immediate

3. Direct Memory Addressing

The operand is a memory location specified by a 32-bit absolute address. In x64, this is limited to the low 4GB address space (compatibility mode) unless used with RIP-relative.

mov eax, [12345678h]    ; absolute 32-bit address
mov DWORD PTR [1234h], 42  ; store to absolute address

4. Base + Displacement

The effective address is calculated as base + displacement. The displacement can be an 8-bit (disp8) or 32-bit (disp32) signed value.

mov eax, [rbp-8]        ; local variable at rbp-8
mov eax, [rcx+16]       ; struct member at offset 16
mov eax, [rsp+0x30]     ; stack parameter
mov eax, [rbx-4]        ; negative displacement

5. Base + Index

The effective address is base + index. The index is a general-purpose register used as an offset.

mov eax, [rbx+rcx]      ; array element: base + index
mov eax, [rax+rdx]      ; pointer + offset

6. Index * Scale

The effective address is index * scale. Valid scale values are 1, 2, 4, 8 (encoded as 00, 01, 10, 11 in the SIB byte).

mov eax, [rcx*4]        ; element at index*4
mov eax, [rdx*8]        ; element at index*8 (array of pointers)
mov eax, [r9*2]         ; 16-bit element array

7. Base + Index * Scale + Displacement

The full SIB (Scale-Index-Base) addressing form. This is the most general addressing mode, combining all components.

mov eax, [rbx+rcx*4+16]        ; array of structs
mov eax, [rbp+r9*8-32]         ; local array with negative offset
mov eax, [rax+rdx*2+0x100]     ; large displacement
mov eax, [r12+r10*4+0x80]      ; base+r12 with r10 scaled

8. RIP-Relative Addressing

In x64, most memory references use RIP-relative addressing by default for code-relative data access. The assembler encodes a 32-bit signed displacement from the current instruction pointer.

mov rax, [rip+label]           ; load from label (relative to RIP)
mov rax, [rip+my_data]         ; access global data
lea rcx, [rip+message]         ; load effective address
jmp [rip+function_ptr]         ; indirect jump via global pointer

RIP-relative addressing is the standard way to access global variables and constants in x64 code, as it avoids the need for absolute 64-bit addresses and produces position-independent code.

9. Segment Overrides

x64 supports fs: and gs: segment overrides for accessing thread-local storage and operating system data structures.

FS Segment

In Windows x64, the fs segment points to the Thread Environment Block (TEB).

mov rax, QWORD PTR fs:[0x30]   ; PEB pointer from TEB
mov eax, DWORD PTR fs:[0x18]   ; LastError from TEB
mov rax, QWORD PTR fs:[0x60]   ; TLS base pointer

GS Segment

In Windows x64, gs segment is used for thread-local storage. In x86-64 Linux, it points to thread-specific data.

mov rax, QWORD PTR gs:[0x00]   ; TLS variable (Win64)
mov rax, QWORD PTR gs:[0x10]   ; thread-specific data (Linux)

; With RIP-relative: TLS combined addressing
mov rax, QWORD PTR gs:[rip+tls_var]

Operand Size Prefixes

Memory operands require size specifiers to disambiguate the operand size:

Prefix | Size | Example
BYTE PTR | 8 bits | mov BYTE PTR [rcx], 0xFF
WORD PTR | 16 bits | mov WORD PTR [rcx], 0x1234
DWORD PTR | 32 bits | mov DWORD PTR [rcx], eax
QWORD PTR | 64 bits | mov QWORD PTR [rcx], rax
XMMWORD PTR | 128 bits | movdqa XMMWORD PTR [rcx], xmm0
YMMWORD PTR | 256 bits | vmovdqa YMMWORD PTR [rcx], ymm0
ZMMWORD PTR | 512 bits | vmovdqa32 ZMMWORD PTR [rcx], zmm0
TBYTE PTR | 80 bits | fld TBYTE PTR [rcx]

SIB (Scale-Index-Base) Encoding

The SIB byte is used when a memory operand involves an index register. Format:

SIB = [Scale 2 bits] [Index 3 bits] [Base 3 bits]

Scale: 00=1, 01=2, 10=4, 11=8
Index: general-purpose register (100 = no index)
Base:  general-purpose register (101 = disp32 if Mod=00)

Special cases:

  • Base = rsp (100): A SIB byte is always required to encode rsp as a base register (to avoid confusion with the ModRM "SIB present" encoding)
  • Index = rsp (100): Means "no index" register is used (only base + displacement)
  • Mod=00, Base=101, Index=100: RIP-relative addressing


Core GPR Mnemonics

This section documents the x86-64 general-purpose register (GPR) instructions supported by PBXA64's assembler. All instructions use Intel syntax.

Data Movement

Mnemonic | Description | Operands
MOV | Move data between registers, memory, and immediates | reg/mem, reg/mem/imm
MOVZX | Move with zero-extension | reg, reg/mem
MOVSX | Move with sign-extension | reg, reg/mem
MOVSXD | Move with sign-extension (32-bit to 64-bit) | reg64, reg/mem32
CMOVcc | Conditional move (see below) | reg, reg/mem
XCHG | Exchange data between operands | reg, reg/mem
BSWAP | Byte swap (reverse endianness) | reg32/64
MOVBE | Move with big-endian conversion (load/store) | reg, mem / mem, reg
MOVABS | Move 64-bit absolute (aliased to MOV with imm64) | reg64, imm64

Conditional Moves (CMOVcc)

Mnemonic | Condition | Flags
CMOVA / CMOVNBE | Above (not below or equal) | CF=0 and ZF=0
CMOVAE / CMOVNB | Above or equal (not below) | CF=0
CMOVB / CMOVNAE | Below (not above or equal) | CF=1
CMOVBE / CMOVNA | Below or equal (not above) | CF=1 or ZF=1
CMOVE / CMOVZ | Equal (zero) | ZF=1
CMOVNE / CMOVNZ | Not equal (not zero) | ZF=0
CMOVG / CMOVNLE | Greater (signed, not less or equal) | ZF=0 and SF=OF
CMOVGE / CMOVNL | Greater or equal (signed, not less) | SF=OF
CMOVL / CMOVNGE | Less (signed, not greater or equal) | SF!=OF
CMOVLE / CMOVNG | Less or equal (signed, not greater) | ZF=1 or SF!=OF
CMOVO | Overflow | OF=1
CMOVNO | Not overflow | OF=0
CMOVS | Sign (negative) | SF=1
CMOVNS | Not sign (non-negative) | SF=0
CMOVP / CMOVPE | Parity (even) | PF=1
CMOVNP / CMOVPO | Not parity (odd) | PF=0

Arithmetic

Mnemonic | Description | Operands
ADD | Integer addition | reg/mem, reg/mem/imm
ADC | Add with carry | reg/mem, reg/mem/imm
SUB | Integer subtraction | reg/mem, reg/mem/imm
SBB | Subtract with borrow | reg/mem, reg/mem/imm
MUL | Unsigned multiply (r/m * AL/AX/EAX/RAX) | reg/mem
IMUL | Signed multiply (multiple forms) | reg/mem / reg, reg/mem / reg, reg/mem, imm
DIV | Unsigned divide (r/m divides AX/EAX/RAX) | reg/mem
IDIV | Signed divide | reg/mem
INC | Increment by 1 | reg/mem
DEC | Decrement by 1 | reg/mem
NEG | Negate (two's complement) | reg/mem
CMP | Compare (sets flags, no result) | reg/mem, reg/mem/imm
TEST | Logical compare (AND sets flags) | reg/mem, reg/mem/imm

The MUL and DIV instructions use implicit source/destination registers:

Operand Size | MUL: r/m * | Result (Product) | DIV: r/m divides | Quotient | Remainder
8-bit | AL | AX | AX | AL | AH
16-bit | AX | DX:AX | DX:AX | AX | DX
32-bit | EAX | EDX:EAX | EDX:EAX | EAX | EDX
64-bit | RAX | RDX:RAX | RDX:RAX | RAX | RDX

The IMUL instruction has three forms:

  • Single operand: imul r/m — same implicit behavior as MUL
  • Two operand: imul reg, r/m — reg = reg * r/m
  • Three operand: imul reg, r/m, imm — reg = r/m * imm

Logical / Bitwise

Mnemonic | Description | Operands
AND | Bitwise AND | reg/mem, reg/mem/imm
OR | Bitwise OR | reg/mem, reg/mem/imm
XOR | Bitwise XOR | reg/mem, reg/mem/imm
NOT | Bitwise NOT (one's complement) | reg/mem
ANDN | Bitwise AND-NOT (BMI1) | reg, reg, reg/mem

Shift / Rotate

Mnemonic | Description | Operands
SHL / SAL | Shift logical/arithmetic left | reg/mem, imm8/CL
SHR | Shift logical right | reg/mem, imm8/CL
SAR | Shift arithmetic right (sign-preserving) | reg/mem, imm8/CL
ROL | Rotate left | reg/mem, imm8/CL
ROR | Rotate right | reg/mem, imm8/CL
RCL | Rotate left through carry | reg/mem, imm8/CL
RCR | Rotate right through carry | reg/mem, imm8/CL
SHLD | Double precision shift left | reg/mem, reg, imm8/CL
SHRD | Double precision shift right | reg/mem, reg, imm8/CL

Stack Operations

Mnemonic | Description | Operands
PUSH | Push onto stack (RSP decremented by 8 in x64) | reg/mem/imm
POP | Pop from stack (RSP incremented by 8 in x64) | reg/mem
PUSHA / PUSHAD | Push all GPRs (not valid in x64 mode) | none
POPA / POPAD | Pop all GPRs (not valid in x64 mode) | none
PUSHF / PUSHFD | Push EFLAGS/RFLAGS | none
POPF / POPFD | Pop EFLAGS/RFLAGS | none
PUSHQ | Push QWORD (implicit 64-bit push) | imm32
ENTER | Make stack frame (push rbp, mov rbp, rsp; sub rsp, X) | imm16, imm8
LEAVE | Destroy stack frame (mov rsp, rbp; pop rbp) | none
Note: In x64 mode, PUSH and POP always operate on 64-bit values (RSP is adjusted by 8). 32-bit and 16-bit push/pop are not encodable in x64. PUSHA/POPA are not available.

Control Transfer

Unconditional Jumps

Mnemonic | Description | Operands
JMP | Unconditional jump | label/reg/mem
CALL | Call procedure (pushes return address) | label/reg/mem
RET | Return from procedure (pops return address) | none / imm16 (pop N bytes)
RETF | Far return (not used in x64) | none / imm16

Conditional Jumps

Mnemonic | Condition | Flags
JA / JNBE | Jump if above | CF=0 and ZF=0
JAE / JNB / JNC | Jump if above or equal | CF=0
JB / JNAE / JC | Jump if below | CF=1
JBE / JNA | Jump if below or equal | CF=1 or ZF=1
JE / JZ | Jump if equal | ZF=1
JNE / JNZ | Jump if not equal | ZF=0
JG / JNLE | Jump if greater (signed) | ZF=0 and SF=OF
JGE / JNL | Jump if greater or equal (signed) | SF=OF
JL / JNGE | Jump if less (signed) | SF!=OF
JLE / JNG | Jump if less or equal (signed) | ZF=1 or SF!=OF
JO | Jump if overflow | OF=1
JNO | Jump if not overflow | OF=0
JS | Jump if sign (negative) | SF=1
JNS | Jump if not sign | SF=0
JP / JPE | Jump if parity even | PF=1
JNP / JPO | Jump if parity odd | PF=0
JCXZ / JECXZ / JRCXZ | Jump if CX/ECX/RCX zero | CX/ECX/RCX=0

Loop Instructions

Mnemonic | Description | Operands
LOOP | Decrement CX/ECX/RCX, jump if not zero | label
LOOPE / LOOPZ | LOOP while equal/zero | label
LOOPNE / LOOPNZ | LOOP while not equal/not zero | label

String Operations

Mnemonic | Description | Operands
MOVS / MOVSB / MOVSW / MOVSD / MOVSQ | Move string (RSI→RDI, adjust by size) | none
CMPS / CMPSB / CMPSW / CMPSD / CMPSQ | Compare string (RSI vs RDI) | none
SCAS / SCASB / SCASW / SCASD / SCASQ | Scan string (compare AL/AX/EAX/RAX with [RDI]) | none
LODS / LODSB / LODSW / LODSD / LODSQ | Load string ([RSI]→AL/AX/EAX/RAX) | none
STOS / STOSB / STOSW / STOSD / STOSQ | Store string (AL/AX/EAX/RAX→[RDI]) | none

String instructions are often combined with the REP prefix for block operations:

cld                     ; clear direction flag (forward)
rep movsb               ; copy RCX bytes from RSI to RDI
rep stosd               ; fill RCX dwords with EAX
repne scasb             ; scan for AL in [RDI], RCX times

Flag Control

Mnemonic | Description
STC | Set Carry Flag (CF=1)
CLC | Clear Carry Flag (CF=0)
CMC | Complement Carry Flag (CF=!CF)
STD | Set Direction Flag (DF=1)
CLD | Clear Direction Flag (DF=0)
STI | Set Interrupt Flag (IF=1)
CLI | Clear Interrupt Flag (IF=0)
LAHF | Load Flags into AH (SF:ZF:0:AF:0:PF:1:CF)
SAHF | Store AH into Flags
SAHF | Store AH into RFLAGS lower byte

Bit Manipulation

Mnemonic | Description | Operands
BT | Bit test (stores bit at position in CF) | reg/mem, reg/imm
BTS | Bit test and set | reg/mem, reg/imm
BTR | Bit test and reset | reg/mem, reg/imm
BTC | Bit test and complement | reg/mem, reg/imm
BSF | Bit scan forward (lowest set bit) | reg, reg/mem
BSR | Bit scan reverse (highest set bit) | reg, reg/mem
POPCNT | Population count (number of set bits) — SSE4.2 | reg, reg/mem
LZCNT | Count leading zeros — BMI1 (via F3 0F BD) | reg, reg/mem
TZCNT | Count trailing zeros — BMI1 | reg, reg/mem

Exchange / Convert

Mnemonic | Description | Operands
XADD | Exchange and add (atomic) | reg/mem, reg
CMPXCHG | Compare and exchange (atomic) | reg/mem, reg
CMPXCHG8B | Compare and exchange 8 bytes (atomic) | mem64
CMPXCHG16B | Compare and exchange 16 bytes (atomic, needs LOCK) | mem128
CBW / CWDE / CDQE | Convert byte to word / word to dword / dword to qword | none (uses AL/AX/EAX)
CWD / CDQ / CQO | Convert word to dword / dword to qword / qword to dqword (DX:AX / EDX:EAX / RDX:RAX) | none
CWDE | Convert word (AX) to doubleword (EAX) with sign-extension | none
CDQE | Convert doubleword (EAX) to quadword (RAX) with sign-extension | none

Atomic / Lock Prefix

The LOCK prefix makes certain instructions atomic on multi-processor systems. Supported instructions:

lock add / lock adc / lock sub / lock sbb / lock and / lock or / lock xor
lock inc / lock dec / lock neg / lock not
lock xadd / lock cmpxchg / lock cmpxchg8b / lock cmpxchg16b
lock bts / lock btr / lock btc

Example:

lock inc DWORD PTR [counter]       ; atomic increment
lock cmpxchg DWORD PTR [ptr], ecx   ; atomic compare-exchange

Legacy / Compatibility

Mnemonic | Description
AAA | ASCII adjust after addition (not valid in x64)
AAS | ASCII adjust after subtraction (not valid in x64)
AAM | ASCII adjust after multiply (not valid in x64)
AAD | ASCII adjust before division (not valid in x64)
DAA | Decimal adjust after addition (not valid in x64)
DAS | Decimal adjust after subtraction (not valid in x64)
Note: The ASCII and decimal adjust instructions are not encodable in x64 mode but the assembler accepts them for source-level compatibility with legacy code.

NOP and Multi-Byte NOPs

Mnemonic | Encoding | Size
NOP | 90 | 1 byte
NOP (2-byte) | 66 90 | 2 bytes
NOP (3-byte) | 0F 1F 00 | 3 bytes
NOP (4-byte) | 0F 1F 40 00 | 4 bytes
NOP (5-byte) | 0F 1F 44 00 00 | 5 bytes
NOP (6-byte) | 66 0F 1F 44 00 00 | 6 bytes
NOP (7-byte) | 0F 1F 80 00 00 00 00 | 7 bytes
NOP (8-byte) | 0F 1F 84 00 00 00 00 00 | 8 bytes
NOP (9-byte) | 66 0F 1F 84 00 00 00 00 00 | 9 bytes


SSE / SSE2 / SSE3 / SSSE3 / SSE4 Mnemonics

All SSE-family instructions operate on 128-bit XMM registers. PBXA64 supports SSE through SSE4.2 with full Intel syntax.

SSE — Streaming SIMD Extensions

Original SSE (KNI/Katmai New Instructions). Single-precision floating-point operations on XMM registers.

SSE Data Movement

Mnemonic | Description | Operands
MOVAPS | Move aligned packed single (16-byte aligned) | xmm, xmm/mem128 / mem128, xmm
MOVUPS | Move unaligned packed single | xmm, xmm/mem128 / mem128, xmm
MOVSS | Move scalar single | xmm, xmm/mem32 / mem32, xmm
MOVLPS | Move low packed single (lower 64 bits) | xmm, mem64 / mem64, xmm
MOVHPS | Move high packed single (upper 64 bits) | xmm, mem64 / mem64, xmm
MOVLHPS | Move low to high packed single | xmm, xmm
MOVHLPS | Move high to low packed single | xmm, xmm
MOVMSKPS | Move sign mask to GPR (4 sign bits → GPR) | reg, xmm

SSE Packed Arithmetic (Single Precision)

Mnemonic | Description | Operands
ADDPS | Add packed single | xmm, xmm/mem128
ADDSS | Add scalar single | xmm, xmm/mem32
SUBPS | Subtract packed single | xmm, xmm/mem128
SUBSS | Subtract scalar single | xmm, xmm/mem32
MULPS | Multiply packed single | xmm, xmm/mem128
MULSS | Multiply scalar single | xmm, xmm/mem32
DIVPS | Divide packed single | xmm, xmm/mem128
DIVSS | Divide scalar single | xmm, xmm/mem32
SQRTPS | Square root packed single | xmm, xmm/mem128
SQRTSS | Square root scalar single | xmm, xmm/mem32
RCPPS | Reciprocal packed single (approximate) | xmm, xmm/mem128
RCPSS | Reciprocal scalar single (approximate) | xmm, xmm/mem32
RSQRTPS | Reciprocal square root packed single (approx) | xmm, xmm/mem128
RSQRTSS | Reciprocal square root scalar single (approx) | xmm, xmm/mem32
MAXPS | Maximum packed single | xmm, xmm/mem128
MAXSS | Maximum scalar single | xmm, xmm/mem32
MINPS | Minimum packed single | xmm, xmm/mem128
MINSS | Minimum scalar single | xmm, xmm/mem32

SSE Logical / Comparison

Mnemonic | Description | Operands
ANDPS | Bitwise AND of packed singles | xmm, xmm/mem128
ANDNPS | Bitwise AND-NOT of packed singles | xmm, xmm/mem128
ORPS | Bitwise OR of packed singles | xmm, xmm/mem128
XORPS | Bitwise XOR of packed singles | xmm, xmm/mem128
CMPPS | Compare packed single (imm8 predicate) | xmm, xmm/mem128, imm8
CMPSS | Compare scalar single (imm8 predicate) | xmm, xmm/mem32, imm8
COMISS | Compare ordered scalar single (sets flags) | xmm, xmm/mem32
UCOMISS | Compare unordered scalar single (sets flags) | xmm, xmm/mem32

CMPPS/CMPSS immediate predicates:

Imm | Predicate | Description
0 | EQ | Equal
1 | LT | Less than
2 | LE | Less than or equal
3 | UNORD | Unordered
4 | NEQ | Not equal
5 | NLT | Not less than
6 | NLE | Not less than or equal
7 | ORD | Ordered

SSE Shuffle / Unpack

Mnemonic | Description | Operands
SHUFPS | Shuffle packed single | xmm, xmm/mem128, imm8
UNPCKHPS | Unpack high packed single | xmm, xmm/mem128
UNPCKLPS | Unpack low packed single | xmm, xmm/mem128

SSE Control

Mnemonic | Description
STMXCSR | Store MXCSR register (control/status)
LDMXCSR | Load MXCSR register
FXRSTOR | Restore x87 and SSE state
FXSAVE | Save x87 and SSE state

SSE2 — Streaming SIMD Extensions 2

Adds double-precision floating-point and integer SIMD operations (MMX-like on XMM).

SSE2 Double-Precision Arithmetic

Mnemonic | Description | Operands
ADDPD | Add packed double | xmm, xmm/mem128
ADDSD | Add scalar double | xmm, xmm/mem64
SUBPD | Subtract packed double | xmm, xmm/mem128
SUBSD | Subtract scalar double | xmm, xmm/mem64
MULPD | Multiply packed double | xmm, xmm/mem128
MULSD | Multiply scalar double | xmm, xmm/mem64
DIVPD | Divide packed double | xmm, xmm/mem128
DIVSD | Divide scalar double | xmm, xmm/mem64
SQRTPS | Square root packed (PS variant in SSE) | xmm, xmm/mem128
SQRTPD | Square root packed double | xmm, xmm/mem128
SQRTSD | Square root scalar double | xmm, xmm/mem64
MAXPD | Maximum packed double | xmm, xmm/mem128
MAXSD | Maximum scalar double | xmm, xmm/mem64
MINPD | Minimum packed double | xmm, xmm/mem128
MINSD | Minimum scalar double | xmm, xmm/mem64

SSE2 Data Movement

Mnemonic | Description | Operands
MOVAPD | Move aligned packed double | xmm, xmm/mem128 / mem128, xmm
MOVUPD | Move unaligned packed double | xmm, xmm/mem128 / mem128, xmm
MOVSD | Move scalar double | xmm, xmm/mem64 / mem64, xmm
MOVLPD | Move low packed double | xmm, mem64 / mem64, xmm
MOVHPD | Move high packed double | xmm, mem64 / mem64, xmm
MOVMSKPD | Move sign mask to GPR (2 bits) | reg, xmm
MOVDQ2Q | Move XMM to MMX register (low quadword) | mm, xmm
MOVQ2DQ | Move MMX to XMM register (low quadword) | xmm, mm

SSE2 Integer Operations (XMM)

Mnemonic | Description | Operands
MOVD | Move doubleword to/from XMM | xmm, reg32/mem32 / reg32, xmm
MOVQ | Move quadword to/from XMM | xmm, reg64/mem64 / reg64/rm, xmm
MOVDQA | Move aligned double quadword (16-byte aligned) | xmm, xmm/mem128 / mem128, xmm
MOVDQU | Move unaligned double quadword | xmm, xmm/mem128 / mem128, xmm
PADDB | Add packed byte integers | xmm, xmm/mem128
PADDW | Add packed word integers | xmm, xmm/mem128
PADDD | Add packed doubleword integers | xmm, xmm/mem128
PADDQ | Add packed quadword integers | xmm, xmm/mem128
PSUBB | Subtract packed byte integers | xmm, xmm/mem128
PSUBW | Subtract packed word integers | xmm, xmm/mem128
PSUBD | Subtract packed doubleword integers | xmm, xmm/mem128
PSUBQ | Subtract packed quadword integers | xmm, xmm/mem128
PMULLW | Multiply packed word integers (low 16 bits) | xmm, xmm/mem128
PMULHW | Multiply packed word integers (high 16 bits) | xmm, xmm/mem128
PMULHUW | Multiply packed word integers (high 16 bits, unsigned) | xmm, xmm/mem128
PMULUDQ | Multiply unsigned doubleword to quadword | xmm, xmm/mem128
PMADDWD | Multiply and add packed word to doubleword | xmm, xmm/mem128
PSADBW | Sum of absolute differences | xmm, xmm/mem128

SSE2 Packed Integer Logical

Mnemonic | Description | Operands
PAND | Bitwise AND of packed integers | xmm, xmm/mem128
PANDN | Bitwise AND-NOT of packed integers | xmm, xmm/mem128
POR | Bitwise OR of packed integers | xmm, xmm/mem128
PXOR | Bitwise XOR of packed integers | xmm, xmm/mem128

SSE2 Packed Shift

Mnemonic | Description | Operands
PSLLW | Shift left logical packed word | xmm, imm8 / xmm
PSLLD | Shift left logical packed doubleword | xmm, imm8 / xmm
PSLLQ | Shift left logical packed quadword | xmm, imm8 / xmm
PSRLW | Shift right logical packed word | xmm, imm8 / xmm
PSRLD | Shift right logical packed doubleword | xmm, imm8 / xmm
PSRLQ | Shift right logical packed quadword | xmm, imm8 / xmm
PSRAW | Shift right arithmetic packed word | xmm, imm8 / xmm
PSRAD | Shift right arithmetic packed doubleword | xmm, imm8 / xmm

SSE2 Comparison

Mnemonic | Description | Operands
CMPPD | Compare packed double (imm8 predicate) | xmm, xmm/mem128, imm8
CMPSD | Compare scalar double (imm8 predicate) | xmm, xmm/mem64, imm8
COMISD | Compare ordered scalar double (sets flags) | xmm, xmm/mem64
UCOMISD | Compare unordered scalar double (sets flags) | xmm, xmm/mem64
PCMPEQB | Compare packed bytes for equality | xmm, xmm/mem128
PCMPEQW | Compare packed words for equality | xmm, xmm/mem128
PCMPEQD | Compare packed doublewords for equality | xmm, xmm/mem128
PCMPGTB | Compare packed bytes for greater than (signed) | xmm, xmm/mem128
PCMPGTW | Compare packed words for greater than | xmm, xmm/mem128
PCMPGTD | Compare packed doublewords for greater than | xmm, xmm/mem128

SSE2 Convert Instructions

Mnemonic | Description | Operands
CVTPD2PS | Convert packed double to packed single | xmm, xmm/mem128
CVTPS2PD | Convert packed single to packed double | xmm, xmm/mem64
CVTSD2SS | Convert scalar double to scalar single | xmm, xmm/mem64
CVTSS2SD | Convert scalar single to scalar double | xmm, xmm/mem32
CVTDQ2PD | Convert packed doubleword to packed double | xmm, xmm/mem64
CVTPD2DQ | Convert packed double to packed doubleword | xmm, xmm/mem128
CVTDQ2PS | Convert packed doubleword to packed single | xmm, xmm/mem128
CVTPS2DQ | Convert packed single to packed doubleword | xmm, xmm/mem128
CVTTPD2DQ | Truncate packed double to packed doubleword | xmm, xmm/mem128
CVTTPS2DQ | Truncate packed single to packed doubleword | xmm, xmm/mem128
CVTTSD2SI | Truncate scalar double to integer | reg32/64, xmm/mem64
CVTTSI2SD | Truncate integer to scalar double | xmm, reg32/64/mem32
CVTSD2SI | Convert scalar double to integer (round) | reg32/64, xmm/mem64
CVTSI2SD | Convert integer to scalar double | xmm, reg32/64/mem32
CVTSS2SI | Convert scalar single to integer (round) | reg32/64, xmm/mem32
CVTSI2SS | Convert integer to scalar single | xmm, reg32/64/mem32
CVTTSS2SI | Truncate scalar single to integer | reg32/64, xmm/mem32

SSE2 Shuffle / Unpack / Pack

Mnemonic | Description | Operands
PACKSSWB | Pack signed words to bytes (saturated) | xmm, xmm/mem128
PACKSSDW | Pack signed doublewords to words (saturated) | xmm, xmm/mem128
PACKUSWB | Pack unsigned words to bytes (unsigned sat) | xmm, xmm/mem128
PUNPCKHBW | Unpack high bytes | xmm, xmm/mem128
PUNPCKHWD | Unpack high words | xmm, xmm/mem128
PUNPCKHDQ | Unpack high doublewords | xmm, xmm/mem128
PUNPCKHQDQ | Unpack high quadwords | xmm, xmm/mem128
PUNPCKLBW | Unpack low bytes | xmm, xmm/mem128
PUNPCKLWD | Unpack low words | xmm, xmm/mem128
PUNPCKLDQ | Unpack low doublewords | xmm, xmm/mem128
PUNPCKLQDQ | Unpack low quadwords | xmm, xmm/mem128
SHUFPD | Shuffle packed double | xmm, xmm/mem128, imm8
PSHUFD | Shuffle packed doublewords | xmm, xmm/mem128, imm8
PSHUFHW | Shuffle packed high words | xmm, xmm/mem128, imm8
PSHUFLW | Shuffle packed low words | xmm, xmm/mem128, imm8
PSHUFB | Shuffle packed bytes (SSSE3) | xmm, xmm/mem128

SSE2 Cache Control

Mnemonic | Description | Operands
MASKMOVDQU | Masked store of packed integers | xmm, xmm
MOVNTDQ | Non-temporal store of packed integers | mem128, xmm
MOVNTI | Non-temporal store of integer (doubleword/quadword) | mem32/64, reg
MOVNTPD | Non-temporal store of packed double | mem128, xmm
PAUSE | Spin-loop hint (improves performance/power) | none

SSE3 — Streaming SIMD Extensions 3

Mnemonic | Description | Operands
ADDSUBPD | Add/subtract packed double (alternating) | xmm, xmm/mem128
ADDSUBPS | Add/subtract packed single (alternating) | xmm, xmm/mem128
HADDPD | Horizontal add packed double | xmm, xmm/mem128
HADDPS | Horizontal add packed single | xmm, xmm/mem128
HSUBPD | Horizontal subtract packed double | xmm, xmm/mem128
HSUBPS | Horizontal subtract packed single | xmm, xmm/mem128
MOVDDUP | Move and duplicate (one to both halves of XMM) | xmm, xmm/mem64
MOVSHDUP | Move and duplicate high singles | xmm, xmm/mem128
MOVSLDUP | Move and duplicate low singles | xmm, xmm/mem128
LDDQU | Load unaligned 128-bit (avoids cache line split) | xmm, mem128
FISTTP | FPU: truncate and store integer (pops x87 stack) | mem16/32/64

SSSE3 — Supplemental SSE3

Mnemonic | Description | Operands
PSIGNB | Sign of packed bytes (negate or zero) | xmm, xmm/mem128
PSIGNW | Sign of packed words | xmm, xmm/mem128
PSIGND | Sign of packed doublewords | xmm, xmm/mem128
PSHUFB | Packed shuffle bytes (permutation table) | xmm, xmm/mem128
PMULHRSW | Packed multiply high with round and scale | xmm, xmm/mem128
PABSB | Packed absolute value of bytes | xmm, xmm/mem128
PABSW | Packed absolute value of words | xmm, xmm/mem128
PABSD | Packed absolute value of doublewords | xmm, xmm/mem128
PHADDSW | Packed horizontal add signed words with saturation | xmm, xmm/mem128
PHSUBW | Packed horizontal subtract words | xmm, xmm/mem128
PHSUBD | Packed horizontal subtract doublewords | xmm, xmm/mem128
PHADDD | Packed horizontal add doublewords | xmm, xmm/mem128
PHADDW | Packed horizontal add words | xmm, xmm/mem128
PMADDUBSW | Multiply unsigned bytes, add adjacent, saturate | xmm, xmm/mem128
PALIGNR | Packed align right (concatenate and shift) | xmm, xmm/mem128, imm8
PHSUBSW | Packed horizontal subtract signed words with saturation | xmm, xmm/mem128

SSE4.1 — SSE4

Mnemonic | Description | Operands
PMULLD | Multiply packed signed doublewords (low 32 bits) | xmm, xmm/mem128
PMULDQ | Multiply packed signed doublewords to quadwords | xmm, xmm/mem128
PCMPEQQ | Compare packed quadwords for equality | xmm, xmm/mem128
PCMPGTQ | Compare packed quadwords for greater than (signed) | xmm, xmm/mem128
PMAXSB | Maximum of packed signed bytes | xmm, xmm/mem128
PMAXSW | Maximum of packed signed words | xmm, xmm/mem128
PMAXSD | Maximum of packed signed doublewords | xmm, xmm/mem128
PMAXUB | Maximum of packed unsigned bytes | xmm, xmm/mem128
PMAXUW | Maximum of packed unsigned words | xmm, xmm/mem128
PMAXUD | Maximum of packed unsigned doublewords | xmm, xmm/mem128
PMINSB | Minimum of packed signed bytes | xmm, xmm/mem128
PMINSW | Minimum of packed signed words | xmm, xmm/mem128
PMINSD | Minimum of packed signed doublewords | xmm, xmm/mem128
PMINUB | Minimum of packed unsigned bytes | xmm, xmm/mem128
PMINUW | Minimum of packed unsigned words | xmm, xmm/mem128
PMINUD | Minimum of packed unsigned doublewords | xmm, xmm/mem128
PINSRB | Insert byte (from GPR or memory) | xmm, reg/mem32, imm8
PINSRD | Insert doubleword | xmm, reg/mem32, imm8
PINSRQ | Insert quadword | xmm, reg/mem64, imm8
PEXTRB | Extract byte to GPR or memory | reg/mem8, xmm, imm8
PEXTRD | Extract doubleword | reg/mem32, xmm, imm8
PEXTRQ | Extract quadword | reg/mem64, xmm, imm8
INSERTPS | Insert packed single (merge from source) | xmm, xmm/mem32, imm8
EXTRACTPS | Extract packed single to GPR/memory | reg/mem32, xmm, imm8
PHMINPOSUW | Packed horizontal min of unsigned words, store position | xmm, xmm/mem128
PMOVSXBW | Move with sign-extension, bytes to words | xmm, xmm/mem64
PMOVSXBD | Move with sign-extension, bytes to doublewords | xmm, xmm/mem32
PMOVSXBQ | Move with sign-extension, bytes to quadwords | xmm, xmm/mem16
PMOVSXWD | Move with sign-extension, words to doublewords | xmm, xmm/mem64
PMOVSXWQ | Move with sign-extension, words to quadwords | xmm, xmm/mem32
PMOVSXDQ | Move with sign-extension, doublewords to quadwords | xmm, xmm/mem64
PMOVZXBW | Move with zero-extension, bytes to words | xmm, xmm/mem64
PMOVZXBD | Move with zero-extension, bytes to doublewords | xmm, xmm/mem32
PMOVZXBQ | Move with zero-extension, bytes to quadwords | xmm, xmm/mem16
PMOVZXWD | Move with zero-extension, words to doublewords | xmm, xmm/mem64
PMOVZXWQ | Move with zero-extension, words to quadwords | xmm, xmm/mem32
PMOVZXDQ | Move with zero-extension, doublewords to quadwords | xmm, xmm/mem64
PBLENDVB | Variable blend of packed bytes (by XMM0 mask) | xmm, xmm/mem128
PBLENDW | Blend of packed words (immediate mask) | xmm, xmm/mem128, imm8
BLENDPD | Blend packed double (immediate mask) | xmm, xmm/mem128, imm8
BLENDPS | Blend packed single (immediate mask) | xmm, xmm/mem128, imm8
BLENDVPD | Variable blend packed double (by XMM0 mask) | xmm, xmm/mem128
BLENDVPS | Variable blend packed single (by XMM0 mask) | xmm, xmm/mem128
DPPS | Dot product of packed single | xmm, xmm/mem128, imm8
DPPD | Dot product of packed double | xmm, xmm/mem128, imm8
MPSADBW | Multiple sum of absolute differences (8-bit) | xmm, xmm/mem128, imm8
ROUNDPS | Round packed single | xmm, xmm/mem128, imm8
ROUNDSS | Round scalar single | xmm, xmm/mem32, imm8
ROUNDPD | Round packed double | xmm, xmm/mem128, imm8
ROUNDSD | Round scalar double | xmm, xmm/mem64, imm8
PTEST | Logical compare of packed integers (sets ZF/CF) | xmm, xmm/mem128
PACKUSDW | Pack signed doublewords to unsigned words (saturated) | xmm, xmm/mem128
MOVNTDQA | Non-temporal load (streaming load hint) | xmm, mem128

SSE4.2 — SSE4.2

Mnemonic | Description | Operands
PCMPGTQ | Compare packed quadwords for greater than (signed) | xmm, xmm/mem128
PCMPEQQ | Compare packed quadwords for equality | xmm, xmm/mem128
CRC32 | Accumulate CRC32C value | reg32/64, reg/mem8/16/32/64
POPCNT | Population count (number of 1-bits) | reg, reg/mem
PCMPESTRI | Packed compare explicit length strings, index | xmm, xmm/mem128, imm8
PCMPESTRM | Packed compare explicit length strings, mask | xmm, xmm/mem128, imm8
PCMPISTRI | Packed compare implicit length strings, index | xmm, xmm/mem128, imm8
PCMPISTRM | Packed compare implicit length strings, mask | xmm, xmm/mem128, imm8

String Text Processing (SSE4.2 imm8 flags)

The string comparison instructions use an imm8 byte to control:

Bits | Field | Values
1:0 | Aggregated result | 00=equal each, 01=equal ordered, 10=equal signed, 11=equal unsigned
3:2 | Polarity | 00=+, 01=negative, 10=masked+, 11=masked-
5:4 | Output selection | 00=least significant index, 01=most significant, 10=first bit set
6 | Intrsx | 0=int byte comparison, 1=unsigned byte comparison


AVX / AVX2 / AVX-512 / FMA Mnemonics

PBXA64 supports AVX (VEX-encoded), AVX2, AVX-512 (EVEX-encoded), and FMA instructions. AVX instructions use 3-operand syntax with a non-destructive destination.

Note: AVX-512 mnemonics use the EVEX prefix and support opmask registers (k0-k7). The assembler accepts both standard mnemonics and AVX-512 variants (e.g., VADDPS and VADDPSZ).

AVX — Floating-Point Arithmetic

Mnemonic | Description | Operands
VADDPS | Add packed single (128/256) | ymm/xmm, ymm/xmm, ymm/mem
VADDPD | Add packed double (128/256) | ymm/xmm, ymm/xmm, ymm/mem
VADDSS | Add scalar single | xmm, xmm, xmm/mem
VADDSD | Add scalar double | xmm, xmm, xmm/mem
VSUBPS | Subtract packed single | ymm/xmm, ymm/xmm, ymm/mem
VSUBPD | Subtract packed double | ymm/xmm, ymm/xmm, ymm/mem
VSUBSS | Subtract scalar single | xmm, xmm, xmm/mem
VSUBSD | Subtract scalar double | xmm, xmm, xmm/mem
VMULPS | Multiply packed single | ymm/xmm, ymm/xmm, ymm/mem
VMULPD | Multiply packed double | ymm/xmm, ymm/xmm, ymm/mem
VMULSS | Multiply scalar single | xmm, xmm, xmm/mem
VMULSD | Multiply scalar double | xmm, xmm, xmm/mem
VDIVPS | Divide packed single | ymm/xmm, ymm/xmm, ymm/mem
VDIVPD | Divide packed double | ymm/xmm, ymm/xmm, ymm/mem
VDIVSS | Divide scalar single | xmm, xmm, xmm/mem
VDIVSD | Divide scalar double | xmm, xmm, xmm/mem
VSQRTPS | Square root packed single | ymm/xmm, ymm/xmm, ymm/mem
VSQRTPD | Square root packed double | ymm/xmm, ymm/xmm, ymm/mem
VSQRTSS | Square root scalar single | xmm, xmm, xmm/mem
VSQRTSD | Square root scalar double | xmm, xmm, xmm/mem
VRCPPS | Reciprocal packed single (approx) | ymm/xmm, ymm/xmm, ymm/mem
VRCPSS | Reciprocal scalar single (approx) | xmm, xmm, xmm/mem
VRSQRTPS | Reciprocal sqrt packed single (approx) | ymm/xmm, ymm/xmm, ymm/mem
VRSQRTSS | Reciprocal sqrt scalar single (approx) | xmm, xmm, xmm/mem
VMAXPS | Maximum packed single | ymm/xmm, ymm/xmm, ymm/mem
VMAXPD | Maximum packed double | ymm/xmm, ymm/xmm, ymm/mem
VMAXSS | Maximum scalar single | xmm, xmm, xmm/mem
VMAXSD | Maximum scalar double | xmm, xmm, xmm/mem
VMINPS | Minimum packed single | ymm/xmm, ymm/xmm, ymm/mem
VMINPD | Minimum packed double | ymm/xmm, ymm/xmm, ymm/mem
VMINSS | Minimum scalar single | xmm, xmm, xmm/mem
VMINSD | Minimum scalar double | xmm, xmm, xmm/mem
VROUNDPS | Round packed single | ymm/xmm, ymm/mem, imm8
VROUNDPD | Round packed double | ymm/xmm, ymm/mem, imm8
VROUNDSS | Round scalar single | xmm, xmm/mem, imm8
VROUNDSD | Round scalar double | xmm, xmm/mem, imm8

AVX — Data Movement

Mnemonic | Description | Operands
VMOVAPS | Move aligned packed single | ymm/xmm, mem / mem, ymm/xmm
VMOVUPS | Move unaligned packed single | ymm/xmm, mem / mem, ymm/xmm
VMOVAPD | Move aligned packed double | ymm/xmm, mem / mem, ymm/xmm
VMOVUPD | Move unaligned packed double | ymm/xmm, mem / mem, ymm/xmm
VMOVSS | Move scalar single | xmm, xmm/mem / mem32, xmm
VMOVSD | Move scalar double | xmm, xmm/mem / mem64, xmm
VMOVD | Move doubleword to/from XMM | xmm, reg/mem / reg, xmm
VMOVQ | Move quadword to/from XMM | xmm, reg/mem / reg, xmm
VMOVDQA | Move aligned double quadword | ymm/xmm, mem / mem, ymm/xmm
VMOVDQU | Move unaligned double quadword | ymm/xmm, mem / mem, ymm/xmm
VMOVLPS | Move low packed single (64-bit) | xmm, xmm, mem64 / mem64, xmm
VMOVHPS | Move high packed single | xmm, xmm, mem64 / mem64, xmm
VMOVLPD | Move low packed double | xmm, xmm, mem64 / mem64, xmm
VMOVHPD | Move high packed double | xmm, xmm, mem64 / mem64, xmm
VMOVSHDUP | Move and duplicate high singles | ymm/xmm, ymm/mem
VMOVSLDUP | Move and duplicate low singles | ymm/xmm, ymm/mem
VMOVDDUP | Move and duplicate one double | ymm/xmm, ymm/mem
VBROADCASTSS | Broadcast single to all elements | ymm/xmm, mem32
VBROADCASTSD | Broadcast double to all elements | ymm, mem64
VBROADCASTF128 | Broadcast 128-bit to all lanes | ymm, mem128

AVX — Logical & Comparison

Mnemonic | Description | Operands
VANDPS | Bitwise AND of packed singles | ymm/xmm, ymm/xmm, ymm/mem
VANDPD | Bitwise AND of packed doubles | ymm/xmm, ymm/xmm, ymm/mem
VANDNPS | Bitwise AND-NOT of packed singles | ymm/xmm, ymm/xmm, ymm/mem
VANDNPD | Bitwise AND-NOT of packed doubles | ymm/xmm, ymm/xmm, ymm/mem
VORPS | Bitwise OR of packed singles | ymm/xmm, ymm/xmm, ymm/mem
VORPD | Bitwise OR of packed doubles | ymm/xmm, ymm/xmm, ymm/mem
VXORPS | Bitwise XOR of packed singles | ymm/xmm, ymm/xmm, ymm/mem
VXORPD | Bitwise XOR of packed doubles | ymm/xmm, ymm/xmm, ymm/mem
VCMPPS | Compare packed single (imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VCMPPD | Compare packed double (imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VCMPSS | Compare scalar single (imm8) | xmm, xmm, xmm/mem, imm8
VCMPSD | Compare scalar double (imm8) | xmm, xmm, xmm/mem, imm8
VCOMISS | Compare ordered scalar single (flags) | xmm, xmm/mem
VCOMISD | Compare ordered scalar double (flags) | xmm, xmm/mem
VUCOMISS | Compare unordered scalar single (flags) | xmm, xmm/mem
VUCOMISD | Compare unordered scalar double (flags) | xmm, xmm/mem
VTESTPS | Test packed single (sets ZF/CF) | ymm/xmm, ymm/xmm
VTESTPD | Test packed double (sets ZF/CF) | ymm/xmm, ymm/xmm
VPTEST | Logical compare of integers (sets ZF/CF) | ymm/xmm, ymm/mem

AVX — Shuffle / Permute

Mnemonic | Description | Operands
VSHUFPS | Shuffle packed single | ymm/xmm, ymm/xmm, ymm/mem, imm8
VSHUFPD | Shuffle packed double | ymm/xmm, ymm/xmm, ymm/mem, imm8
VPERMILPS | Permute in-lane packed single | ymm/xmm, ymm/mem, imm8
VPERMILPD | Permute in-lane packed double | ymm/xmm, ymm/mem, imm8
VPERM2F128 | Permute 128-bit lanes | ymm, ymm, ymm/mem, imm8
VUNPCKHPS | Unpack high packed single | ymm/xmm, ymm/xmm, ymm/mem
VUNPCKLPS | Unpack low packed single | ymm/xmm, ymm/xmm, ymm/mem
VUNPCKHPD | Unpack high packed double | ymm/xmm, ymm/xmm, ymm/mem
VUNPCKLPD | Unpack low packed double | ymm/xmm, ymm/xmm, ymm/mem

AVX — Integer Operations

Mnemonic | Description | Operands
VPADDB | Add packed bytes | ymm/xmm, ymm/xmm, ymm/mem
VPADDW | Add packed words | ymm/xmm, ymm/xmm, ymm/mem
VPADDD | Add packed doublewords | ymm/xmm, ymm/xmm, ymm/mem
VPADDQ | Add packed quadwords | ymm/xmm, ymm/xmm, ymm/mem
VPSUBB | Subtract packed bytes | ymm/xmm, ymm/xmm, ymm/mem
VPSUBW | Subtract packed words | ymm/xmm, ymm/xmm, ymm/mem
VPSUBD | Subtract packed doublewords | ymm/xmm, ymm/xmm, ymm/mem
VPSUBQ | Subtract packed quadwords | ymm/xmm, ymm/xmm, ymm/mem
VPAND | Bitwise AND | ymm/xmm, ymm/xmm, ymm/mem
VPANDN | Bitwise AND-NOT | ymm/xmm, ymm/xmm, ymm/mem
VPOR | Bitwise OR | ymm/xmm, ymm/xmm, ymm/mem
VPXOR | Bitwise XOR | ymm/xmm, ymm/xmm, ymm/mem
VPSLLW | Shift left logical words | ymm/xmm, xmm/mem, imm8
VPSLLD | Shift left logical doublewords | ymm/xmm, xmm/mem, imm8
VPSLLQ | Shift left logical quadwords | ymm/xmm, xmm/mem, imm8
VPSRLW | Shift right logical words | ymm/xmm, xmm/mem, imm8
VPSRLD | Shift right logical doublewords | ymm/xmm, xmm/mem, imm8
VPSRLQ | Shift right logical quadwords | ymm/xmm, xmm/mem, imm8
VPSRAW | Shift right arithmetic words | ymm/xmm, xmm/mem, imm8
VPSRAD | Shift right arithmetic doublewords | ymm/xmm, xmm/mem, imm8
VPMULLW | Multiply packed words (low) | ymm/xmm, ymm/xmm, ymm/mem
VPMULLD | Multiply packed doublewords (low) | ymm/xmm, ymm/xmm, ymm/mem
VPMULHW | Multiply packed words (high) | ymm/xmm, ymm/xmm, ymm/mem
VPMULHUW | Multiply packed words (high, unsigned) | ymm/xmm, ymm/xmm, ymm/mem
VPMULUDQ | Multiply unsigned dword to qword | ymm/xmm, ymm/xmm, ymm/mem
VPMULDQ | Multiply signed dword to qword | ymm/xmm, ymm/xmm, ymm/mem
VPMADDUBSW | Multiply unsigned bytes, add adjacent, saturate | ymm/xmm, ymm/xmm, ymm/mem
VPMADDWD | Multiply and add words to doublewords | ymm/xmm, ymm/xmm, ymm/mem
VPSADBW | Sum of absolute differences | ymm/xmm, ymm/xmm, ymm/mem

AVX — Convert Instructions

Mnemonic | Description | Operands
VCVTPD2PS | Convert packed double to single | ymm/xmm, ymm/xmm/mem
VCVTPS2PD | Convert packed single to double | ymm/xmm, ymm/xmm/mem
VCVTSD2SS | Convert scalar double to single | xmm, xmm, xmm/mem
VCVTSS2SD | Convert scalar single to double | xmm, xmm, xmm/mem
VCVTDQ2PD | Convert packed dword to double | ymm/xmm, xmm/mem
VCVTPD2DQ | Convert packed double to dword | ymm/xmm, ymm/xmm/mem
VCVTDQ2PS | Convert packed dword to single | ymm/xmm, ymm/mem
VCVTPS2DQ | Convert packed single to dword | ymm/xmm, ymm/mem
VCVTTPD2DQ | Truncate packed double to dword | ymm/xmm, ymm/mem
VCVTTPS2DQ | Truncate packed single to dword | ymm/xmm, ymm/mem
VCVTTSD2SI | Truncate scalar double to integer | reg, xmm/mem
VCVTTSS2SI | Truncate scalar single to integer | reg, xmm/mem
VCVTSI2SD | Convert integer to scalar double | xmm, xmm, reg/mem
VCVTSI2SS | Convert integer to scalar single | xmm, xmm, reg/mem
VCVTSD2SI | Convert scalar double to integer | reg, xmm/mem
VCVTSS2SI | Convert scalar single to integer | reg, xmm/mem
VCVTPS2PH | Convert packed single to half precision | xmm/mem, ymm/xmm, imm8
VCPH2PS | Convert half precision to packed single | ymm/xmm, xmm/mem

AVX — Blend / Select / Horizontal

Mnemonic | Description | Operands
VBLENDPS | Blend packed single (imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VBLENDPD | Blend packed double (imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VBLENDVPS | Variable blend packed single | ymm/xmm, ymm/xmm, ymm/mem
VBLENDVPD | Variable blend packed double | ymm/xmm, ymm/xmm, ymm/mem
VPBLENDVB | Variable blend packed bytes | ymm/xmm, ymm/xmm, ymm/mem
VPBLENDW | Blend packed words (imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VDPPS | Dot product packed single (imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VDPPD | Dot product packed double (imm8) | xmm, xmm, xmm/mem, imm8
VHADDPS | Horizontal add packed single | ymm/xmm, ymm/xmm, ymm/mem
VHADDPD | Horizontal add packed double | ymm/xmm, ymm/xmm, ymm/mem
VHSUBPS | Horizontal subtract packed single | ymm/xmm, ymm/xmm, ymm/mem
VHSUBPD | Horizontal subtract packed double | ymm/xmm, ymm/xmm, ymm/mem
VADDSUBPS | Add/subtract alternating packed single | ymm/xmm, ymm/xmm, ymm/mem
VADDSUBPD | Add/subtract alternating packed double | ymm/xmm, ymm/xmm, ymm/mem

AVX2

Mnemonic | Description | Operands
VPBROADCASTB | Broadcast byte to all elements | ymm/xmm, reg/mem
VPBROADCASTW | Broadcast word to all elements | ymm/xmm, reg/mem
VPBROADCASTD | Broadcast dword to all elements | ymm/xmm, reg/mem
VPBROADCASTQ | Broadcast qword to all elements | ymm/xmm, reg/mem
VBROADCASTI128 | Broadcast 128-bit to all lanes | ymm, mem128
VPERM2I128 | Permute 128-bit integer lanes | ymm, ymm, ymm/mem, imm8
VPERMD | Permute doublewords | ymm, ymm, ymm/mem
VPERMPD | Permute double-precision floats | ymm, ymm, ymm/mem, imm8
VPERMPS | Permute single-precision floats | ymm, ymm, ymm/mem
VPERMQ | Permute quadwords | ymm, ymm/mem, imm8
VPERMIL2PS | Two-source permute of singles | ymm/xmm, ymm/xmm, ymm/mem, imm4
VPERMIL2PD | Two-source permute of doubles | ymm/xmm, ymm/xmm, ymm/mem, imm4
VGATHERDPD | Gather double with dword indices | ymm/xmm, mem, ymm/xmm
VGATHERQPD | Gather double with qword indices | ymm/xmm, mem, ymm/xmm
VGATHERDPS | Gather single with dword indices | ymm/xmm, mem, ymm/xmm
VGATHERQPS | Gather single with qword indices | ymm/xmm, mem, ymm/xmm
VPGATHERDD | Gather dwords with dword indices | ymm/xmm, mem, ymm/xmm
VPGATHERDQ | Gather dwords with qword indices | ymm/xmm, mem, ymm/xmm
VPGATHERQD | Gather qwords with dword indices | ymm/xmm, mem, ymm/xmm
VPGATHERQQ | Gather qwords with qword indices | ymm/xmm, mem, ymm/xmm
VPMASKMOVD | Masked move of dwords | ymm/xmm, ymm/xmm, mem
VPMASKMOVQ | Masked move of qwords | ymm/xmm, ymm/xmm, mem
VPSLLVD | Variable shift left logical dwords | ymm/xmm, ymm/xmm, ymm/mem
VPSLLVQ | Variable shift left logical qwords | ymm/xmm, ymm/xmm, ymm/mem
VPSRLVD | Variable shift right logical dwords | ymm/xmm, ymm/xmm, ymm/mem
VPSRLVQ | Variable shift right logical qwords | ymm/xmm, ymm/xmm, ymm/mem
VPSRAVD | Variable shift right arith dwords | ymm/xmm, ymm/xmm, ymm/mem
VPMOVSXBW | Sign-extend bytes to words | ymm/xmm, xmm/mem
VPMOVSXBD | Sign-extend bytes to dwords | ymm/xmm, xmm/mem
VPMOVSXBQ | Sign-extend bytes to qwords | ymm/xmm, xmm/mem
VPMOVSXWD | Sign-extend words to dwords | ymm/xmm, xmm/mem
VPMOVSXWQ | Sign-extend words to qwords | ymm/xmm, xmm/mem
VPMOVSXDQ | Sign-extend dwords to qwords | ymm/xmm, xmm/mem
VPMOVZXBW | Zero-extend bytes to words | ymm/xmm, xmm/mem
VPMOVZXBD | Zero-extend bytes to dwords | ymm/xmm, xmm/mem
VPMOVZXBQ | Zero-extend bytes to qwords | ymm/xmm, xmm/mem
VPMOVZXWD | Zero-extend words to dwords | ymm/xmm, xmm/mem
VPMOVZXWQ | Zero-extend words to qwords | ymm/xmm, xmm/mem
VPMOVZXDQ | Zero-extend dwords to qwords | ymm/xmm, xmm/mem
VPSHUFB | Shuffle packed bytes (per-lane) | ymm/xmm, ymm/xmm, ymm/mem
VPSHUFD | Shuffle packed dwords (per-lane, imm8) | ymm/xmm, ymm/mem, imm8
VPSHUFHW | Shuffle packed high words (imm8) | ymm/xmm, ymm/mem, imm8
VPSHUFLW | Shuffle packed low words (imm8) | ymm/xmm, ymm/mem, imm8
VPABSB | Absolute value of bytes | ymm/xmm, ymm/mem
VPABSW | Absolute value of words | ymm/xmm, ymm/mem
VPABSD | Absolute value of dwords | ymm/xmm, ymm/mem
VPMAXSB | Maximum of signed bytes | ymm/xmm, ymm/xmm, ymm/mem
VPMAXSW | Maximum of signed words | ymm/xmm, ymm/xmm, ymm/mem
VPMAXSD | Maximum of signed dwords | ymm/xmm, ymm/xmm, ymm/mem
VPMAXUB | Maximum of unsigned bytes | ymm/xmm, ymm/xmm, ymm/mem
VPMAXUW | Maximum of unsigned words | ymm/xmm, ymm/xmm, ymm/mem
VPMAXUD | Maximum of unsigned dwords | ymm/xmm, ymm/xmm, ymm/mem
VPMINSB | Minimum of signed bytes | ymm/xmm, ymm/xmm, ymm/mem
VPMINSW | Minimum of signed words | ymm/xmm, ymm/xmm, ymm/mem
VPMINSD | Minimum of signed dwords | ymm/xmm, ymm/xmm, ymm/mem
VPMINUB | Minimum of unsigned bytes | ymm/xmm, ymm/xmm, ymm/mem
VPMINUW | Minimum of unsigned words | ymm/xmm, ymm/xmm, ymm/mem
VPMINUD | Minimum of unsigned dwords | ymm/xmm, ymm/xmm, ymm/mem
VPINSRB | Insert byte | xmm, xmm, reg/mem, imm8
VPINSRD | Insert dword | xmm, xmm, reg/mem, imm8
VPINSRQ | Insert qword | xmm, xmm, reg/mem, imm8
VPEXTRB | Extract byte | reg/mem, xmm, imm8
VPEXTRD | Extract dword | reg/mem, xmm, imm8
VPEXTRQ | Extract qword | reg/mem, xmm, imm8
VPMOVMSKB | Move byte mask to GPR | reg, ymm/xmm
VPHADDW | Horizontal add words | ymm/xmm, ymm/xmm, ymm/mem
VPHADDD | Horizontal add dwords | ymm/xmm, ymm/xmm, ymm/mem
VPHADDSW | Horizontal add words with saturation | ymm/xmm, ymm/xmm, ymm/mem
VPHSUBW | Horizontal subtract words | ymm/xmm, ymm/xmm, ymm/mem
VPHSUBD | Horizontal subtract dwords | ymm/xmm, ymm/xmm, ymm/mem
VPHSUBSW | Horizontal subtract words with saturation | ymm/xmm, ymm/xmm, ymm/mem
VPMULHRSW | Multiply high with round and scale | ymm/xmm, ymm/xmm, ymm/mem
VPSIGNB | Sign of bytes | ymm/xmm, ymm/xmm, ymm/mem
VPSIGNW | Sign of words | ymm/xmm, ymm/xmm, ymm/mem
VPSIGND | Sign of dwords | ymm/xmm, ymm/xmm, ymm/mem
VPALIGNR | Align right (concatenate and shift, imm8) | ymm/xmm, ymm/xmm, ymm/mem, imm8
VPCMPEQB | Compare bytes for equality | ymm/xmm, ymm/xmm, ymm/mem
VPCMPEQW | Compare words for equality | ymm/xmm, ymm/xmm, ymm/mem
VPCMPEQD | Compare dwords for equality | ymm/xmm, ymm/xmm, ymm/mem
VPCMPEQQ | Compare qwords for equality | ymm/xmm, ymm/xmm, ymm/mem
VPCMPGTB | Compare bytes for greater than | ymm/xmm, ymm/xmm, ymm/mem
VPCMPGTW | Compare words for greater than | ymm/xmm, ymm/xmm, ymm/mem
VPCMPGTD | Compare dwords for greater than | ymm/xmm, ymm/xmm, ymm/mem
VPCMPGTQ | Compare qwords for greater than | ymm/xmm, ymm/xmm, ymm/mem
VINSERTI128 | Insert 128-bit integer lane (imm8) | ymm, ymm, xmm/mem, imm8
VEXTRACTI128 | Extract 128-bit integer lane (imm8) | xmm/mem, ymm, imm8
VINSERTF128 | Insert 128-bit float lane (imm8) | ymm, ymm, xmm/mem, imm8
VEXTRACTF128 | Extract 128-bit float lane (imm8) | xmm/mem, ymm, imm8

FMA — Fused Multiply-Add

Mnemonic | Description | Operands
VFMADD132PS | FMA: a*b+c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMADD213PS | FMA: a*b+c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMADD231PS | FMA: a*b+c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMADD132PD | FMA: a*b+c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMADD213PD | FMA: a*b+c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMADD231PD | FMA: a*b+c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMADD132SS | FMA: a*b+c (single, scalar) | xmm, xmm, xmm/mem
VFMADD213SS | FMA: a*b+c (single, scalar) | xmm, xmm, xmm/mem
VFMADD231SS | FMA: a*b+c (single, scalar) | xmm, xmm, xmm/mem
VFMADD132SD | FMA: a*b+c (double, scalar) | xmm, xmm, xmm/mem
VFMADD213SD | FMA: a*b+c (double, scalar) | xmm, xmm, xmm/mem
VFMADD231SD | FMA: a*b+c (double, scalar) | xmm, xmm, xmm/mem
VFMSUB132PS | FMA: a*b-c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMSUB213PS | FMA: a*b-c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMSUB231PS | FMA: a*b-c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMSUB132PD | FMA: a*b-c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMSUB213PD | FMA: a*b-c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMSUB231PD | FMA: a*b-c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFMSUB132SS | FMA: a*b-c (single, scalar) | xmm, xmm, xmm/mem
VFMSUB213SS | FMA: a*b-c (single, scalar) | xmm, xmm, xmm/mem
VFMSUB231SS | FMA: a*b-c (single, scalar) | xmm, xmm, xmm/mem
VFMSUB132SD | FMA: a*b-c (double, scalar) | xmm, xmm, xmm/mem
VFMSUB213SD | FMA: a*b-c (double, scalar) | xmm, xmm, xmm/mem
VFMSUB231SD | FMA: a*b-c (double, scalar) | xmm, xmm, xmm/mem
VFMADDSUB132PS | FMA: a*b+c / a*b-c (alternating, packed single) | ymm/xmm, ymm/xmm, ymm/mem
VFMADDSUB213PS | FMA: a*b+c / a*b-c (alternating, packed single) | ymm/xmm, ymm/xmm, ymm/mem
VFMADDSUB231PS | FMA: a*b+c / a*b-c (alternating, packed single) | ymm/xmm, ymm/xmm, ymm/mem
VFMADDSUB132PD | FMA: a*b+c / a*b-c (alternating, packed double) | ymm/xmm, ymm/xmm, ymm/mem
VFMADDSUB213PD | FMA: a*b+c / a*b-c (alternating, packed double) | ymm/xmm, ymm/xmm, ymm/mem
VFMADDSUB231PD | FMA: a*b+c / a*b-c (alternating, packed double) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD132PS | FMA: -(a*b)+c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD213PS | FMA: -(a*b)+c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD231PS | FMA: -(a*b)+c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD132PD | FMA: -(a*b)+c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD213PD | FMA: -(a*b)+c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD231PD | FMA: -(a*b)+c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMADD132SS | FMA: -(a*b)+c (single, scalar) | xmm, xmm, xmm/mem
VFNMADD213SS | FMA: -(a*b)+c (single, scalar) | xmm, xmm, xmm/mem
VFNMADD231SS | FMA: -(a*b)+c (single, scalar) | xmm, xmm, xmm/mem
VFNMADD132SD | FMA: -(a*b)+c (double, scalar) | xmm, xmm, xmm/mem
VFNMADD213SD | FMA: -(a*b)+c (double, scalar) | xmm, xmm, xmm/mem
VFNMADD231SD | FMA: -(a*b)+c (double, scalar) | xmm, xmm, xmm/mem
VFNMSUB132PS | FMA: -(a*b)-c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMSUB213PS | FMA: -(a*b)-c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMSUB231PS | FMA: -(a*b)-c (single, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMSUB132PD | FMA: -(a*b)-c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMSUB213PD | FMA: -(a*b)-c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMSUB231PD | FMA: -(a*b)-c (double, packed) | ymm/xmm, ymm/xmm, ymm/mem
VFNMSUB132SS | FMA: -(a*b)-c (single, scalar) | xmm, xmm, xmm/mem
VFNMSUB213SS | FMA: -(a*b)-c (single, scalar) | xmm, xmm, xmm/mem
VFNMSUB231SS | FMA: -(a*b)-c (single, scalar) | xmm, xmm, xmm/mem
VFNMSUB132SD | FMA: -(a*b)-c (double, scalar) | xmm, xmm, xmm/mem
VFNMSUB213SD | FMA: -(a*b)-c (double, scalar) | xmm, xmm, xmm/mem
VFNMSUB231SD | FMA: -(a*b)-c (double, scalar) | xmm, xmm, xmm/mem

AVX-512 — Key Differences

AVX-512 extends YMM to 512-bit ZMM registers and adds opmask registers k0-k7. Mnemonics use an optional Z suffix or the EVEX prefix. Key new instructions:

Mnemonic | Description | Operands
VMOVDQA32 | Move aligned dword/qword (with opmask) | zmm, mem / mem, zmm
VMOVDQA64 | Move aligned qword (with opmask) | zmm, mem / mem, zmm
VMOVDQU32 | Move unaligned dword/qword (with opmask) | zmm, mem / mem, zmm
VMOVDQU64 | Move unaligned qword (with opmask) | zmm, mem / mem, zmm
VPABSQ | Absolute value of qwords | zmm, zmm/mem
VPMAXSQ | Maximum of signed qwords | zmm, zmm, zmm/mem
VPMINSQ | Minimum of signed qwords | zmm, zmm, zmm/mem
VPMAXUQ | Maximum of unsigned qwords | zmm, zmm, zmm/mem
VPMINUQ | Minimum of unsigned qwords | zmm, zmm, zmm/mem
VPCONFLICTD | Detect conflicts in dword vector | zmm, zmm/mem
VPCONFLICTQ | Detect conflicts in qword vector | zmm, zmm/mem
VPLZCNTD | Count leading zeros in dword vector | zmm, zmm/mem
VPLZCNTQ | Count leading zeros in qword vector | zmm, zmm/mem
VCOMPRESS | Compress packed elements (by mask) | zmm, zmm/mem
VEXPAND | Expand packed elements (by mask) | zmm, zmm/mem
VPCOMPRESSD | Compress packed dwords | zmm, zmm/mem
VPCOMPRESSQ | Compress packed qwords | zmm, zmm/mem
VPEXPANDD | Expand packed dwords | zmm, zmm/mem
VPEXPANDQ | Expand packed qwords | zmm, zmm/mem
VPERMI2B | Permute bytes with index and mask | zmm, zmm, zmm/mem
VPERMI2W | Permute words with index and mask | zmm, zmm, zmm/mem
VPERMI2D | Permute dwords with index and mask | zmm, zmm, zmm/mem
VPERMI2Q | Permute qwords with index and mask | zmm, zmm, zmm/mem
VPERMT2B | Permute bytes with index and mask (two-source) | zmm, zmm, zmm/mem
VPERMT2W | Permute words with index and mask (two-source) | zmm, zmm, zmm/mem
VPERMT2D | Permute dwords with index and mask (two-source) | zmm, zmm, zmm/mem
VPERMT2Q | Permute qwords with index and mask (two-source) | zmm, zmm, zmm/mem
VGETMANTPS | Extract normalized mantissa from single | zmm, zmm/mem, imm8
VGETMANTPD | Extract normalized mantissa from double | zmm, zmm/mem, imm8
VFPCLASSPS | Test packed single for class (NaN/Inf/Zero) | zmm, zmm/mem, imm8
VFPCLASSPD | Test packed double for class | zmm, zmm/mem, imm8
VRCP14PS | 14-bit reciprocal packed single | zmm, zmm/mem
VRCP14PD | 14-bit reciprocal packed double | zmm, zmm/mem
VRCP14SS | 14-bit reciprocal scalar single | xmm, xmm, xmm/mem
VRCP14SD | 14-bit reciprocal scalar double | xmm, xmm, xmm/mem
VRSQRT14PS | 14-bit reciprocal sqrt packed single | zmm, zmm/mem
VRSQRT14PD | 14-bit reciprocal sqrt packed double | zmm, zmm/mem
VSCALEFPS | Scale packed single by power of 2 | zmm, zmm, zmm/mem
VSCALEFPD | Scale packed double by power of 2 | zmm, zmm, zmm/mem
VFIXUPIMMPS | Fix up packed single (NaN handling) | zmm, zmm, zmm/mem, imm8
VFIXUPIMMPD | Fix up packed double (NaN handling) | zmm, zmm, zmm/mem, imm8
VREDUCEPS | Reduce packed single (round to N bits) | zmm, zmm/mem, imm8
VREDUCEPD | Reduce packed double (round to N bits) | zmm, zmm/mem, imm8
VRNDSCALEPS | Round packed single with scale | zmm, zmm/mem, imm8
VRNDSCALEPD | Round packed double with scale | zmm, zmm/mem, imm8
VPMADD52HUQ | Multiply and add 52-bit high unsigned qwords | zmm, zmm, zmm/mem
VPMADD52LUQ | Multiply and add 52-bit low unsigned qwords | zmm, zmm, zmm/mem
VPSLLVW | Variable shift left logical words | zmm, zmm, zmm/mem
VPSLLVDQ | Variable shift left logical dword/qword | zmm, zmm, zmm/mem
VPSRAVQ | Variable shift right arithmetic qwords | zmm, zmm, zmm/mem
VPSRLVW | Variable shift right logical words | zmm, zmm, zmm/mem
VPSRLVDQ | Variable shift right logical dword/qword | zmm, zmm, zmm/mem
VPTERNLOGD | Three-input bitwise operation (dword) | zmm, zmm, zmm/mem, imm8
VPTERNLOGQ | Three-input bitwise operation (qword) | zmm, zmm, zmm/mem, imm8
VPMOVDB | Pack and truncate dwords to bytes (narrow) | mem, zmm / xmm, zmm
VPMOVDW | Pack and truncate dwords to words (narrow) | mem, zmm / xmm, zmm
VPMOVQB | Pack and truncate qwords to bytes (narrow) | mem, zmm / xmm, zmm
VPMOVQD | Pack and truncate qwords to dwords (narrow) | mem, zmm / xmm, zmm
VPMOVQW | Pack and truncate qwords to words (narrow) | mem, zmm / xmm, zmm
VPMOVWB | Pack and truncate words to bytes (narrow) | mem, zmm / xmm, zmm
VPOPCNTB | Population count of bytes (vector) | zmm, zmm/mem
VPOPCNTW | Population count of words (vector) | zmm, zmm/mem
VPOPCNTD | Population count of dwords (vector) | zmm, zmm/mem
VPOPCNTQ | Population count of qwords (vector) | zmm, zmm/mem
VDBPSADBW | Double block packed sum of abs diffs (words) | zmm, zmm, zmm/mem, imm8
VSHUFI32X4 | Shuffle 128-bit lanes of 32-bit elements | zmm, zmm, zmm/mem, imm8
VSHUFI64X2 | Shuffle 128-bit lanes of 64-bit elements | zmm, zmm, zmm/mem, imm8

Mask Register Instructions (k0-k7)

AVX-512 introduces 8 mask registers (k0-k7) for predicated operation. k0 is hardwired to all-ones (no masking). The typical syntax is vmovdqa32 zmm1 {k1}{z}, zmm2.

Mnemonic | Description | Operands
KMOVB/KMOVW/KMOVD/KMOVQ | Move mask register to/from GPR or memory | k, k/reg/mem
KADDB/KADDW/KADDD/KADDQ | Add two mask registers | k, k, k
KANDB/KANDW/KANDD/KANDQ | Bitwise AND of mask registers | k, k, k
KANDNB/KANDNW/KANDND/KANDNQ | Bitwise AND-NOT of mask registers | k, k, k
KORB/KORW/KORD/KORQ | Bitwise OR of mask registers | k, k, k
KXORB/KXORW/KXORD/KXORQ | Bitwise XOR of mask registers | k, k, k
KXNORB/KXNORW/KXNORD/KXNORQ | Bitwise XNOR of mask registers | k, k, k
KNOTB/KNOTW/KNOTD/KNOTQ | Bitwise NOT of mask register | k, k
KORTESTB/KORTESTW/KORTESTD/KORTESTQ | OR test (sets CF/ZF if result is all-ones/zero) | k, k
KSHIFTLB/KSHIFTLW/KSHIFTLD/KSHIFTLQ | Shift left mask register by imm8 | k, k, imm8
KSHIFTRB/KSHIFTRW/KSHIFTRD/KSHIFTRQ | Shift right mask register by imm8 | k, k, imm8

AVX-512BW — Byte/Word Extensions

Mnemonic | Description | Operands
VPADDB | Add packed bytes (512-bit with opmask) | zmm, zmm, zmm/mem
VPADDW | Add packed words (512-bit with opmask) | zmm, zmm, zmm/mem
VPSUBB | Subtract packed bytes (512-bit with opmask) | zmm, zmm, zmm/mem
VPSUBW | Subtract packed words (512-bit with opmask) | zmm, zmm, zmm/mem
VPSLLVW | Variable shift left logical words | zmm, zmm, zmm/mem
VPSRLVW | Variable shift right logical words | zmm, zmm, zmm/mem
VPSRAVW | Variable shift right arithmetic words | zmm, zmm, zmm/mem
VPABSB | Absolute value of bytes (512-bit) | zmm, zmm/mem
VPABSW | Absolute value of words (512-bit) | zmm, zmm/mem
VPMOVB2M | Move byte mask from vector to k register | k, zmm
VPMOVW2M | Move word mask from vector to k register | k, zmm
VPMOVM2B | Move mask from k register to byte vector | zmm, k
VPMOVM2W | Move mask from k register to word vector | zmm, k
VDBPSADBW | Double block packed sum of abs diffs (words) | zmm, zmm, zmm/mem, imm8

AVX-512DQ — Double/Quadword Extensions

Mnemonic | Description | Operands
VPMULLQ | Multiply packed signed qwords (low 64 bits) | zmm, zmm, zmm/mem
VPANDQ | Bitwise AND of qwords | zmm, zmm, zmm/mem
VPORQ | Bitwise OR of qwords | zmm, zmm, zmm/mem
VPXORQ | Bitwise XOR of qwords | zmm, zmm, zmm/mem
VPABSQ | Absolute value of qwords | zmm, zmm/mem
VPMOVD2M | Move dword mask from vector to k register | k, zmm
VPMOVQ2M | Move qword mask from vector to k register | k, zmm
VPMOVM2D | Move mask from k register to dword vector | zmm, k
VPMOVM2Q | Move mask from k register to qword vector | zmm, k

AVX-512ER — Exponential/Reciprocal

Introduced in Intel Xeon Phi (Knights Landing). Provides high-precision exponential, reciprocal, and reciprocal sqrt.

Mnemonic | Description | Operands
VEXP2PD | Base-2 exponential approximation (double, packed) | zmm, zmm/mem
VEXP2PS | Base-2 exponential approximation (single, packed) | zmm, zmm/mem
VRCP28PD | 28-bit reciprocal approximation (double, packed) | zmm, zmm/mem
VRCP28PS | 28-bit reciprocal approximation (single, packed) | zmm, zmm/mem
VRCP28SD | 28-bit reciprocal approximation (double, scalar) | xmm, xmm, xmm/mem
VRCP28SS | 28-bit reciprocal approximation (single, scalar) | xmm, xmm, xmm/mem
VRSQRT28PD | 28-bit reciprocal sqrt approximation (double, packed) | zmm, zmm/mem
VRSQRT28PS | 28-bit reciprocal sqrt approximation (single, packed) | zmm, zmm/mem
VRSQRT28SD | 28-bit reciprocal sqrt approximation (double, scalar) | xmm, xmm, xmm/mem
VRSQRT28SS | 28-bit reciprocal sqrt approximation (single, scalar) | xmm, xmm, xmm/mem

AVX-512PF — Prefetch Gather/Scatter

Prefetch hints for gather/scatter operations (Xeon Phi only). Uses VSIB addressing.

Mnemonic | Description | Operands
VGATHERPF0DPD | Prefetch gather double, intent level 0 | mem (VSIB)
VGATHERPF0DPS | Prefetch gather single, intent level 0 | mem (VSIB)
VGATHERPF1DPD | Prefetch gather double, intent level 1 | mem (VSIB)
VGATHERPF1DPS | Prefetch gather single, intent level 1 | mem (VSIB)
VSCATTERPF0DPD | Prefetch scatter double, intent level 0 | mem (VSIB)
VSCATTERPF0DPS | Prefetch scatter single, intent level 0 | mem (VSIB)
VSCATTERPF1DPD | Prefetch scatter double, intent level 1 | mem (VSIB)
VSCATTERPF1DPS | Prefetch scatter single, intent level 1 | mem (VSIB)

AVX-512VPOPCNTDQ — Vector Popcount

Mnemonic | Description | Operands
VPOPCNTD | Population count of dword elements | zmm, zmm/mem
VPOPCNTQ | Population count of qword elements | zmm, zmm/mem

AVX-512BITALG — Bit Algorithms

Mnemonic | Description | Operands
VPOPCNTB | Population count of byte elements | zmm, zmm/mem
VPOPCNTW | Population count of word elements | zmm, zmm/mem
VPSHUFBITQMB | Shuffle bits in qword to byte mask | k, zmm, zmm/mem

AVX-512VBMI — Vector Byte Manipulation

Mnemonic | Description | Operands
VPERMB | Permute bytes across lanes | zmm, zmm, zmm/mem
VPERMI2B | Two-source permute of bytes with index | zmm, zmm, zmm/mem
VPERMT2B | Two-source permute of bytes (index in dest) | zmm, zmm, zmm/mem
VPMULTISHIFTQB | Multiple shift and concatenate qwords to bytes | zmm, zmm, zmm/mem

AVX-512VBMI2 — Byte/Word Compress/Expand

Mnemonic | Description | Operands
VCOMPRESSB | Compress packed bytes (by mask) | zmm, zmm/mem
VCOMPRESSW | Compress packed words (by mask) | zmm, zmm/mem
VEXPANDB | Expand packed bytes (by mask) | zmm, zmm/mem
VEXPANDW | Expand packed words (by mask) | zmm, zmm/mem
VPSHLDV | Variable shift left double (concatenate shift) | zmm, zmm, zmm/mem
VPSHLDVW | Variable shift left double words | zmm, zmm, zmm/mem
VPSHRDV | Variable shift right double (concatenate shift) | zmm, zmm, zmm/mem
VPSHRDVW | Variable shift right double words | zmm, zmm, zmm/mem

GFNI — Galois Field New Instructions

Mnemonic | Description | Operands
VGF2P8AFFINEINVQB | Galois field affine transformation inverse | zmm/xmm, zmm/xmm, zmm/mem, imm8
VGF2P8AFFINEQB | Galois field affine transformation | zmm/xmm, zmm/xmm, zmm/mem, imm8
VGF2P8MULB | Galois field multiply bytes (GF(2^8)) | zmm/xmm, zmm/xmm, zmm/mem

AVX-512 — Scatter Stores

Mnemonic | Description | Operands
VSCATTERDPS | Scatter packed single using dword indices | mem, zmm
VSCATTERDPD | Scatter packed double using dword indices | mem, zmm
VSCATTERQPS | Scatter packed single using qword indices | mem, zmm
VSCATTERQPD | Scatter packed double using qword indices | mem, zmm

AVX-512 — Additional Operations

Mnemonic | Description | Operands
VALIGND | Align dwords (concatenate and shift) | zmm, zmm, zmm/mem, imm8
VALIGNQ | Align qwords (concatenate and shift) | zmm, zmm, zmm/mem, imm8
VBLENDMPD | Blend packed double from mask | zmm, zmm, zmm/mem
VBLENDMPS | Blend packed single from mask | zmm, zmm, zmm/mem
VPBLENDMD | Blend packed dwords from mask | zmm, zmm, zmm/mem
VPBLENDMQ | Blend packed qwords from mask | zmm, zmm, zmm/mem
VCOMPRESSPS | Compress packed single (by mask) | zmm, zmm/mem
VCOMPRESSPD | Compress packed double (by mask) | zmm, zmm/mem
VCOMPRESSD | Compress packed dwords (by mask) | zmm, zmm/mem
VCOMPRESSQ | Compress packed qwords (by mask) | zmm, zmm/mem
VEXPANDPS | Expand packed single (by mask) | zmm, zmm/mem
VEXPANDPD | Expand packed double (by mask) | zmm, zmm/mem
VEXPANDD | Expand packed dwords (by mask) | zmm, zmm/mem
VEXPANDQ | Expand packed qwords (by mask) | zmm, zmm/mem
VFIXUPIMMSD | Fix up scalar double (NaN handling) | xmm, xmm, xmm/mem, imm8
VFIXUPIMMSS | Fix up scalar single (NaN handling) | xmm, xmm, xmm/mem, imm8
VREDUCESD | Reduce scalar double (round to N bits) | xmm, xmm, xmm/mem, imm8
VREDUCESS | Reduce scalar single (round to N bits) | xmm, xmm, xmm/mem, imm8
VRNDSCALESD | Round scalar double with scale | xmm, xmm, xmm/mem, imm8
VRNDSCALESS | Round scalar single with scale | xmm, xmm, xmm/mem, imm8
VRANGESD | Range restriction scalar double | xmm, xmm, xmm/mem, imm8
VRANGESS | Range restriction scalar single | xmm, xmm, xmm/mem, imm8
VGETEXPSD | Extract exponent scalar double | xmm, xmm, xmm/mem
VGETEXPSS | Extract exponent scalar single | xmm, xmm, xmm/mem
VGETMANTSD | Extract normalized mantissa scalar double | xmm, xmm, xmm/mem, imm8
VGETMANTSS | Extract normalized mantissa scalar single | xmm, xmm, xmm/mem, imm8
VPSRAVQ | Variable shift right arithmetic qwords | zmm, zmm, zmm/mem
VPERMI2W | Two-source permute of words with index | zmm, zmm, zmm/mem
VPERMT2W | Two-source permute of words (index in dest) | zmm, zmm, zmm/mem
VPERMI2D | Two-source permute of dwords with index | zmm, zmm, zmm/mem
VPERMI2Q | Two-source permute of qwords with index | zmm, zmm, zmm/mem
VPERMI2PS | Two-source permute of singles with index | zmm, zmm, zmm/mem
VPERMI2PD | Two-source permute of doubles with index | zmm, zmm, zmm/mem
VPERMT2D | Two-source permute of dwords (index in dest) | zmm, zmm, zmm/mem
VPERMT2Q | Two-source permute of qwords (index in dest) | zmm, zmm, zmm/mem
VPERMT2PS | Two-source permute of singles (index in dest) | zmm, zmm, zmm/mem
VPERMT2PD | Two-source permute of doubles (index in dest) | zmm, zmm, zmm/mem
Note: AVX-512 instructions can use opmask registers (k1-k7). Opmask zero (k0) is hardwired to all-ones and acts as "no mask". The typical syntax is: vmovdqa32 zmm1 {k1}{z}, zmm2 where {k1} enables masking and {z} enables zeroing-mask mode. The suffix suffix (32/64 for dword/qword element size) determines which elements the mask applies to.


BMI1 / BMI2 Mnemonics

Bit Manipulation Instruction Sets 1 and 2, introduced in Intel Haswell (2013) and AMD Jaguar/Piledriver. These instructions accelerate bitfield operations and arbitrary-precision arithmetic.

BMI1

Mnemonic | Description | Operands | CPUID Flag
ANDN | Bitwise AND-NOT: dst = ~src1 & src2 | reg, reg, reg/mem | BMI1
BEXTR | Bit field extract: extract contiguous bits | reg, reg/mem, reg/imm | BMI1
BLSI | Isolate lowest set bit: dst = src & -src | reg, reg/mem | BMI1
BLSMSK | Mask up to lowest set bit: dst = src ^ (src-1) | reg, reg/mem | BMI1
BLSR | Reset lowest set bit: dst = src & (src-1) | reg, reg/mem | BMI1
TZCNT | Count trailing zeros (uses F3 prefix unlike BSF) | reg, reg/mem | BMI1

BMI1 Examples

andn   eax, ebx, ecx      ; eax = ~ebx & ecx
bextr  eax, ecx, 8        ; eax = bits 15:8 of ecx (start=8, len=8)
blsi   eax, [var]         ; eax = [var] & -[var]
blsmsk eax, edx           ; eax = edx ^ (edx-1)
blsr   eax, ecx           ; eax = ecx & (ecx-1)  -- clears lowest set bit
tzcnt  eax, ebx           ; eax = count trailing zeros in ebx

BMI2

Mnemonic | Description | Operands | CPUID Flag
BZHI | Zero high bits: if index<operand_size, dst=src & mask | reg, reg/mem, reg | BMI2
MULX | Unsigned multiply without affecting flags | reg, reg, reg/mem | BMI2
PDEP | Parallel bits deposit: scatter bits using mask | reg, reg, reg/mem | BMI2
PEXT | Parallel bits extract: gather bits using mask | reg, reg, reg/mem | BMI2
RORX | Rotate right by immediate (no flags affected) | reg, reg/mem, imm8 | BMI2
SARX | Shift arithmetic right by variable (no flags) | reg, reg/mem, reg | BMI2
SHLX | Shift left logical by variable (no flags) | reg, reg/mem, reg | BMI2
SHRX | Shift right logical by variable (no flags) | reg, reg/mem, reg | BMI2

BMI2 Examples

bzhi   eax, ebx, ecx       ; zero bits above position ecx in ebx
mulx   edx, eax, ecx       ; edx:eax = ecx * [implicit rdx:rax]
pdep   rax, rbx, rcx       ; deposit bits of rbx using mask in rcx
pext   rax, rbx, rcx       ; extract bits of rbx using mask in rcx
rorx   eax, [var], 8       ; rotate right by 8, no flags
sarx   eax, ebx, ecx       ; arithmetic shift right ebx by ecx
shlx   eax, ebx, ecx       ; logical shift left ebx by ecx
shrx   eax, ebx, ecx       ; logical shift right ebx by ecx

ADCX / ADOX — Arbitrary-Precision Add

Intel Haswell introduced ADCX and ADOX for multi-precision arithmetic with independent carry chains.

Mnemonic | Description | Operands
ADCX | Add with carry (uses CF flag only) | reg32/64, reg/mem
ADOX | Add with overflow (uses OF flag only) | reg32/64, reg/mem
; Multi-precision addition with dual carry chains
adcx  rcx, [rsi+0]         ; add with carry chain 1 (CF)
adox  rdx, [rsi+8]         ; add with carry chain 2 (OF)
adcx  r8,  [rsi+16]        ; continue chain 1
adox  r9,  [rsi+24]        ; continue chain 2
Note: ADCX uses the Carry Flag (CF) exclusively. ADOX uses the Overflow Flag (OF) exclusively. This allows two independent carry chains to proceed in parallel, doubling throughput for large integer arithmetic.


AES / SHA / CLMUL / CRC32 Mnemonics

Crypto / Security Mnemonics

AES-NI (AES New Instructions), SHA extensions, Carry-less Multiplication (CLMUL), and CRC32 instructions for cryptographic and checksum acceleration.

AES-NI — AES New Instructions

Introduced in Intel Westmere (2010). Hardware-accelerated AES encryption/decryption.

Mnemonic | Description | Operands
AESENC | Perform one round of AES encryption | xmm, xmm/mem128
AESENCLAST | Perform last round of AES encryption | xmm, xmm/mem128
AESDEC | Perform one round of AES decryption | xmm, xmm/mem128
AESDECLAST | Perform last round of AES decryption | xmm, xmm/mem128
AESIMC | Inverse mix columns (for key expansion) | xmm, xmm/mem128
AESKEYGENASSIST | Assist for AES round key generation | xmm, xmm/mem128, imm8

AES Examples

; AES-128 encryption of one block
aeskeygenassist xmm2, xmm1, 1  ; generate round key 1
aesenc          xmm0, xmm2      ; round 1
; ...
aesenclast      xmm0, xmmk10    ; final round

; AES decryption
aesdec          xmm0, xmm2      ; round 1
aesdeclast      xmm0, xmmk10    ; final round
aesimc          xmm1, xmm0      ; inverse mix columns

VAES — AES with AVX/AVX-512

Mnemonic | Description | Operands
VAESENC | VEX/EVEX AES round encryption | xmm/ymm/zmm, xmm/ymm/zmm, mem
VAESENCLAST | VEX/EVEX AES last round encryption | xmm/ymm/zmm, xmm/ymm/zmm, mem
VAESDEC | VEX/EVEX AES round decryption | xmm/ymm/zmm, xmm/ymm/zmm, mem
VAESDECLAST | VEX/EVEX AES last round decryption | xmm/ymm/zmm, xmm/ymm/zmm, mem
VAESIMC | VEX AES inverse mix columns | xmm, xmm/mem
VAESKEYGENASSIST | VEX AES key generation assist | xmm, xmm/mem, imm8

PCLMULQDQ — Carry-Less Multiplication

Mnemonic | Description | Operands
PCLMULQDQ | Carry-less multiply of two 64-bit halves | xmm, xmm/mem128, imm8
VPCLMULQDQ | VEX/EVEX carry-less multiply | xmm/ymm/zmm, xmm/ymm/zmm, mem, imm8

The imm8 operand selects which 64-bit halves to multiply:

Bits | Field | Value
1:0 | SRC2 select | 00=low qword, 01=high qword
5:4 | SRC1 (first operand) select | 00=low qword, 01=high qword
; GF(2^128) multiplication for AES-GCM
pclmulqdq xmm1, xmm2, 0x00   ; low * low
pclmulqdq xmm1, xmm2, 0x01   ; low * high
pclmulqdq xmm1, xmm2, 0x10   ; high * low
pclmulqdq xmm1, xmm2, 0x11   ; high * high

SHA Extensions

Introduced in Intel Goldmont (2016) and Ice Lake. Hardware-accelerated SHA-1 and SHA-256.

SHA-1

Mnemonic | Description | Operands
SHA1RNDS4 | SHA-1 four rounds | xmm, xmm/mem128, imm8
SHA1NEXTE | SHA-1 next four e-values | xmm, xmm/mem128
SHA1MSG1 | SHA-1 message schedule update 1 | xmm, xmm/mem128
SHA1MSG2 | SHA-1 message schedule update 2 | xmm, xmm/mem128

SHA-256

Mnemonic | Description | Operands
SHA256RNDS2 | SHA-256 two rounds | xmm, xmm/mem128
SHA256MSG1 | SHA-256 message schedule update 1 | xmm, xmm/mem128
SHA256MSG2 | SHA-256 message schedule update 2 | xmm, xmm/mem128

CRC32 — Cyclic Redundancy Check

Introduced in SSE4.2 (Intel Nehalem, 2008). Hardware-accelerated CRC-32C (Castagnoli polynomial 0x1EDC6F41).

Mnemonic | Description | Operands
CRC32 | Accumulate CRC32C value into destination | reg32/64, reg/mem8/16/32/64

The first operand (destination) holds the accumulated CRC value. The second operand (source) is the input data. The source size determines which encoding is used.

; CRC32 examples - source size determines encoding
crc32 eax, byte  [ptr]      ; 8-bit input
crc32 eax, word  [ptr]      ; 16-bit input (66 prefix)
crc32 eax, dword [ptr]      ; 32-bit input (default)
crc32 rax, qword [ptr]      ; 64-bit input (REX.W prefix)

; Chained CRC32 computation
xor   eax, eax              ; start with CRC = 0
crc32 eax, byte [rsi]       ; CRC-32C of byte 0
crc32 eax, byte [rsi+1]     ; accumulate byte 1
crc32 eax, byte [rsi+2]     ; accumulate byte 2
; ... or use rep crc32 with larger operands

GFNI — Galois Field New Instructions

Introduced in Ice Lake (2020). Provides SIMD GF(2^8) multiplication and affine transformations for cryptography and post-quantum algorithms.

Mnemonic | Description | Operands
GF2P8AFFINEINVQB | Galois field affine transformation inverse (legacy SSE) | xmm, xmm/mem128, imm8
GF2P8AFFINEQB | Galois field affine transformation (legacy SSE) | xmm, xmm/mem128, imm8
GF2P8MULB | Galois field multiply bytes (legacy SSE) | xmm, xmm/mem128

See AVX Mnemonics for VEX/EVEX-encoded variants (VGF2P8*) supporting 128/256/512-bit operations with opmask.

SM3 / SM4 — Chinese Crypto (optional)

Mnemonic | Description | Operands
SM3MSG1 | SM3 message schedule update 1 | xmm, xmm/mem
SM3MSG2 | SM3 message schedule update 2 | xmm, xmm/mem
SM4ENC | SM4 one round encryption | xmm, xmm/mem
SM4ENC4 | SM4 four rounds encryption | xmm, xmm/mem


System Instructions

System instructions provide access to CPU features, control registers, memory management, I/O ports, and performance monitoring. Most require elevated privileges (ring 0 / kernel mode).

Warning: Many system instructions are privileged and will cause an exception (#GP) if executed at ring 3 (user mode). Use with care in PB programs, typically via a device driver or kernel service.

CPU Identification & Feature Detection

Mnemonic | Description | Operands | Privilege
CPUID | CPU identification (EAX=leaf, ECX=subleaf, returns EAX/EBX/ECX/EDX) | none | User
XGETBV | Read extended control register XCR (ECX=index) | none | User
XSETBV | Write extended control register XCR (must be ring 0) | none | Ring 0
; CPUID example: check for AVX2 support
mov eax, 7               ; leaf 7 = extended features
mov ecx, 0               ; subleaf 0
cpuid
test ebx, 20             ; bit 5 = AVX2
jnz has_avx2

; XGETBV example: check XCR0 for AVX state
mov ecx, 0               ; XCR0
xgetbv                   ; returns EDX:EAX
test eax, 6              ; bits 1+2 = XMM + YMM state enabled
jnz avx_enabled

Timestamp & Performance Counters

Mnemonic | Description | Operands | Privilege
RDTSC | Read time-stamp counter (returns EDX:EAX) | none | User
RDTSCP | Read TSC + processor ID (returns EDX:EAX, ECX=IA32_TSC_AUX) | none | User
RDPMC | Read performance monitoring counter (ECX=counter) | none | User*
; High-resolution timing
rdtsc                    ; eax = TSC low, edx = TSC high
shl rdx, 32
or  rax, rdx             ; rax = 64-bit TSC value
; ...
rdtscp                   ; similar but with processor ID in ecx
mov [processor_id], ecx

Control Registers

Mnemonic | Description | Operands | Privilege
MOV CR0, reg | Write control register CR0 | reg64 | Ring 0
MOV reg, CR0 | Read control register CR0 | reg64 | Ring 0
MOV CR2, reg | Write CR2 (page fault linear address) | reg64 | Ring 0
MOV reg, CR2 | Read CR2 | reg64 | Ring 0
MOV CR3, reg | Write CR3 (page table base address) | reg64 | Ring 0
MOV reg, CR3 | Read CR3 | reg64 | Ring 0
MOV CR4, reg | Write CR4 (extension control) | reg64 | Ring 0
MOV reg, CR4 | Read CR4 | reg64 | Ring 0
MOV CR8, reg | Write CR8 (task priority, x64 only) | reg64 | Ring 0
MOV reg, CR8 | Read CR8 | reg64 | Ring 0

Debug Registers

Mnemonic | Description | Operands | Privilege
MOV DR0-DR7, reg | Write debug register | reg64 | Ring 0
MOV reg, DR0-DR7 | Read debug register | reg64 | Ring 0

Descriptor Table Instructions

Mnemonic | Description | Operands | Privilege
SGDT | Store Global Descriptor Table register | mem80 (pseudo-descriptor) | User
SIDT | Store Interrupt Descriptor Table register | mem80 | User
SLDT | Store Local Descriptor Table register | reg/mem16/64 | User
SMSW | Store Machine Status Word (CR0 low 16 bits) | reg/mem16/64 | User
STR | Store Task Register | reg/mem16/64 | User
LGDT | Load Global Descriptor Table register | mem80 (pseudo-descriptor) | Ring 0
LIDT | Load Interrupt Descriptor Table register | mem80 | Ring 0
LLDT | Load Local Descriptor Table register | reg/mem16/64 | Ring 0
LMSW | Load Machine Status Word | reg/mem16/64 | Ring 0
LTR | Load Task Register | reg/mem16/64 | Ring 0

Segment Register Instructions

Mnemonic | Description | Operands | Privilege
LAR | Load access rights (segment descriptor) | reg, reg/mem16 | User
LSL | Load segment limit | reg, reg/mem16 | User
VERR | Verify segment for reading | reg/mem16 | User
VERW | Verify segment for writing | reg/mem16 | User
MOV segment, reg | Load segment register (CS/DS/ES/FS/GS/SS) | reg16/64 | Ring 0*
MOV reg, segment | Read segment register | reg16/64 | User

I/O Port Instructions

Mnemonic | Description | Operands | Privilege
IN | Input from I/O port | AL/AX/EAX, DX/imm8 | Ring 0*
OUT | Output to I/O port | DX/imm8, AL/AX/EAX | Ring 0*
INS / INSB / INSW / INSD | Input string from I/O port to memory | none (uses DX, RDI) | Ring 0*
OUTS / OUTSB / OUTSW / OUTSD | Output string to I/O port from memory | none (uses DX, RSI) | Ring 0*
Note: I/O instructions may be accessible at ring 3 if the I/O Permission Bitmap (IOPL) allows it. On Windows, user-mode I/O access is generally blocked.

Interrupt / Exception

Mnemonic | Description | Operands | Privilege
INT n | Software interrupt (raises interrupt n) | imm8 | User
INT3 | Breakpoint interrupt (#BP, debugger trap) | none | User
INTO | Interrupt on overflow (if OF=1, #OF) | none | User
BOUND | Check array bounds (not valid in x64) | reg, mem | User
IRET / IRETD / IRETQ | Interrupt return (pops CS:RIP, RFLAGS, stack) | none | Ring 0
; Software interrupt
mov ah, 0x09             ; DOS: write string
mov dx, offset message
int 0x21                 ; DOS system call

; Debugger breakpoint
int3                     ; same as 'bp' in PB

; Simple system call (Linux x64)
mov eax, 60              ; sys_exit
xor edi, edi             ; exit code 0
syscall                  ; invoke kernel

System Call Instructions

Mnemonic | Description | Operands | Privilege
SYSCALL | Fast system call (AMD/x64 Linux: RCX=RIP, R11=RFLAGS) | none | User
SYSRET | Return from fast system call | none | Ring 0
SYSENTER | Fast system call (Intel): sets EIP=MSR SYSENTER_EIP | none | User
SYSEXIT | Fast return from SYSENTER | none | Ring 0

TLS / Segment Base Instructions

Mnemonic | Description | Operands | Privilege
SWAPGS | Swap GS base register with KernelGSBase (MSR C0000102) | none | Ring 0
RDFSBASE | Read FS base address | reg64 | User
RDGSBASE | Read GS base address | reg64 | User
WRFSBASE | Write FS base address | reg64 | Ring 0*
WRGSBASE | Write GS base address | reg64 | Ring 0*
; Windows: get PEB via GS segment
mov rax, QWORD PTR gs:[0x60]   ; PEB address

; Linux x64: swap GS for kernel entry
swapgs                         ; exchange user GS with kernel GS
mov QWORD PTR gs:[0x10], rsp   ; save kernel stack pointer

Model-Specific Registers (MSR)

Mnemonic | Description | Operands | Privilege
RDMSR | Read MSR (ECX=MSR address, returns EDX:EAX) | none | Ring 0
WRMSR | Write MSR (ECX=address, EDX:EAX=value) | none | Ring 0
; Read IA32_APIC_BASE MSR
mov ecx, 0x1B             ; IA32_APIC_BASE MSR
rdmsr                     ; edx:eax = APIC base address
; edx = high 32 bits, eax = low 32 bits
shl rdx, 32
or  rax, rdx              ; rax = full 64-bit value

Cache / Memory Management

Mnemonic | Description | Operands | Privilege
CLFLUSH | Flush cache line containing address | mem8 | User
CLFLUSHOPT | Optimized flush cache line | mem8 | User
CLWB | Cache line write back (retain in cache) | mem8 | User
INVD | Invalidate internal caches (no writeback) | none | Ring 0
WBINVD | Write back and invalidate caches | none | Ring 0
INVLPG | Invalidate TLB entry for address | mem8 | Ring 0
INVPCID | Invalidate TLB entries with PCID | reg, mem128 | Ring 0
INVEPT | Invalidate Extended Page Table entries | reg, mem128 | Ring 0
INVVPID | Invalidate VPID TLB entries | reg, mem128 | Ring 0
WFENCE | Wait for SFENCE (no-op in modern CPUs) | none | User

Power Management / Halt

Mnemonic | Description | Operands | Privilege
HLT | Halt processor until next interrupt | none | Ring 0
MWAIT | Monitor and wait for writes | none (uses EAX/ECX) | Ring 0
MONITOR | Set up address range for MWAIT | none (uses RAX/RCX/RDX) | Ring 0
MWAITX | Extended MWAIT with timing hint | none | Ring 0
MONITORX | Extended MONITOR | none | Ring 0
CLZERO | Zero cache line (AMD only) | none | User
PAUSE | Spin-wait hint (reduces power/improves HT) | none | User
UMONITOR | User-level MONITOR | reg | User
UMWAIT | User-level MWAIT | reg, imm8 | User
TPAUSE | Timed PAUSE | reg, imm8 | User
; Spin-wait loop with PAUSE
spin_loop:
    pause
    cmp DWORD PTR [lock_var], 0
    jne spin_loop

; Kernel halt
hlt                        ; stop CPU until interrupt

Miscellaneous / Obsolete

Mnemonic | Description | Operands
SALC | Set AL based on carry (undocumented, CF→AL=0xFF/0x00) | none
UD0 | Undefined instruction (raises #UD) | none
UD1 | Undefined instruction (two operands form) | reg, reg/mem
UD2 | Undefined instruction (guaranteed #UD, 2 bytes: 0F 0B) | none
XLAT / XLATB | Translate byte (AL = [RBX + AL]) | none
WAIT / FWAIT | Wait for FPU/Math coprocessor | none
NOP | No operation (including multi-byte NOPs) | none


SGX / VMX / CET Mnemonics

SGX / VMX / CET Instructions

SGX (Software Guard Extensions), VMX (Virtual Machine Extensions), and CET (Control-flow Enforcement Technology). These are specialized security and virtualization instruction sets available on recent Intel processors.

SGX — Software Guard Extensions

SGX enables creation of isolated enclaves within the address space. Instructions are divided into three privilege levels:

ENCLS — Supervisor (Ring 0)

Mnemonic | Description
ENCLS[ECREATE] | Create an enclave
ENCLS[EADD] | Add a page to an enclave
ENCLS[EEXTEND] | Extend the measurement of an enclave page
ENCLS[EINIT] | Initialize the enclave (complete measurement)
ENCLS[ELDB] | Load an enclave page as blocked
ENCLS[ELDU] | Load an enclave page as unblocked
ENCLS[EPA] | Add a version array page
ENCLS[EREMOVE] | Remove a page from an enclave
ENCLS[ETRACK] | Activate tracking of enclave page modifications
ENCLS[EWB] | Write back and evict an enclave page
ENCLS[EAUG] | Add a page for dynamic growth (SGX2)
ENCLS[EMODPR] | Modify page permissions/restrictions (SGX2)
ENCLS[EMODT] | Modify page type (SGX2)
ENCLS[EDECRD] | Decrement page reference count (SGX2)
ENCLS[ETRACKC] | Activate redirect tracking for child enclaves

ENCLU — User (Ring 3, inside enclave)

Mnemonic | Description
ENCLU[EENTER] | Enter an enclave
ENCLU[ERESUME] | Resume an enclave after interrupt/exception
ENCLU[EEXIT] | Exit the enclave
ENCLU[EGETKEY] | Get a hardware-derived key from the enclave
ENCLU[EREPORT] | Create a cryptographic report
ENCLU[EACCEPT] | Accept a page modification (SGX2)
ENCLU[EMODPE] | Modify the permitted page protections (SGX2)
ENCLU[EACCEPTCOPY] | Accept a copied page (SGX2)

ENCLV — Virtualization (Ring 0, VMM)

Mnemonic | Description
ENCLV[EDECLASSIFY] | Clear the classified attributes of a page
ENCLV[ETRACKC] | Track child enclave page modifications
; SGX enclave entry (inside host)
lea rcx, [secs]            ; SGX Enclave Control Structure
lea rdx, [base_address]
lea r8,  [source_page]
mov eax, 0                 ; ECREATE
ENCLS

; SGX enclave entry (inside enclave)
lea rax, [tcs]             ; Thread Control Structure
lea rbx, [aep]             ; Asynchronous Exit Pointer
mov rcx, [entry_address]   ; Entry point in enclave
ENCLU[EENTER]

VMX — Virtual Machine Extensions

Hardware virtualization support for hypervisors/VMMs.

VMX Management

Mnemonic | Description | Operands
VMXON | Enter VMX operation | mem64 (VMXON region ptr)
VMXOFF | Exit VMX operation | none
VMPTRLD | Load current VMCS pointer | mem64
VMPTRST | Store current VMCS pointer | mem64
VMCLEAR | Clear VMCS (flush cached state) | mem64
VMREAD | Read field from VMCS | reg, reg/mem
VMWRITE | Write field to VMCS | reg/mem, reg

VM Entry/Exit

Mnemonic | Description
VMLAUNCH | Launch virtual machine (first entry)
VMRESUME | Resume virtual machine (subsequent entries)

VM-Exit Handling

Mnemonic | Description | Operands
VMCALL | Call VMM from guest (VM-exit) | none
VMFUNC | VM function call (leaf in EAX) | none

VM Shadow / TLB Control

Mnemonic | Description | Operands
INVEPT | Invalidate EPT (Extended Page Table) | reg, mem128
INVVPID | Invalidate VPID (Virtual Processor ID) | reg, mem128
VMPTRLD | Load VMCS pointer | mem64
; Basic VMM: launch a guest
vmxon [vmxon_region]       ; enter VMX operation
vmptrld [vmcs]             ; load VMCS
; ... set up VMCS fields ...
vmlaunch                   ; launch guest
; ... on VM exit ...
vmresume                   ; resume guest
vmxoff                     ; exit VMX operation

CET — Control-flow Enforcement Technology

CET provides shadow stack (hardware-enforced return address protection) and indirect branch tracking (IBT). Available on Intel Tiger Lake+.

Shadow Stack (SS)

Mnemonic | Description | Operands
RDSSP | Read shadow stack pointer | reg64
INCSSP | Increment shadow stack pointer by N*8 | reg32
SAVEPREVSSP | Save previous shadow stack pointer | none
RSTORSSP | Restore shadow stack pointer | mem64
WRSS | Write to shadow stack (supervisor) | mem64, reg64
WRUSS | Write to shadow stack (user) | mem64, reg64
SETSSBSY | Mark shadow stack as busy | none
CLRSSBSY | Clear shadow stack busy flag | mem64

Indirect Branch Tracking (IBT)

Mnemonic | Description | Encoding
ENDBR64 | End of branch (64-bit, at branch targets) | F3 0F 1E FA
ENDBR32 | End of branch (32-bit) | F3 0F 1E FB
NOTRACK | Prefix: suppress IBT check for next JMP/CALL | F2 prefix

CET Examples

; Shadow stack save/restore
rdssp  rax                ; read current shadow stack pointer
mov    [saved_ssp], rax   ; save it for later restore

; Set up shadow stack for a new context
rstorssp [new_ss_frame]   ; restore shadow stack pointer
saveprevssp               ; save previous SSP
ret                       ; shadow stack will also pop

; IBT-compliant function
func:
    endbr64               ; required at every indirect branch target
    push rbp
    mov rbp, rsp
    ; ... function body ...
    pop rbp
    ret

; Indirect call through function pointer
call_func:
    endbr64
    mov rax, [pfn]        ; load function pointer
    notrack call rax       ; call without IBT check (NOTRACK prefix)
Note: CET shadow stack requires operating system support (Windows 10 20H1+ kernel-mode, Windows 11 user-mode). On CPUs without CET, these instructions raise #UD.


MMX Mnemonics

MMX (MultiMedia eXtensions) provides 64-bit SIMD operations on MMX registers (mm0-mm7), which are aliased to the x87 FPU stack. PBXA64 supports all 57 MMX instructions. MMX registers are 64 bits wide and operate on packed byte, word, or doubleword integers.

Note: MMX registers share physical storage with x87 FPU registers. Always use EMMS after MMX code before using FPU instructions. On modern CPUs, prefer SSE2 for integer SIMD.

Data Movement

Mnemonic | Description | Operands
MOVD | Move doubleword to/from MMX register | mm, reg32/mem32 / reg32, mm
MOVQ | Move quadword to/from MMX register | mm, mm/mem64 / mem64, mm

Packed Arithmetic

Mnemonic | Description | Operands
PADDB | Add packed bytes (wrap on overflow) | mm, mm/mem64
PADDW | Add packed words (wrap) | mm, mm/mem64
PADDD | Add packed doublewords (wrap) | mm, mm/mem64
PADDSB | Add packed bytes with signed saturation | mm, mm/mem64
PADDSW | Add packed words with signed saturation | mm, mm/mem64
PADDUSB | Add packed bytes with unsigned saturation | mm, mm/mem64
PADDUSW | Add packed words with unsigned saturation | mm, mm/mem64
PSUBB | Subtract packed bytes (wrap) | mm, mm/mem64
PSUBW | Subtract packed words (wrap) | mm, mm/mem64
PSUBD | Subtract packed doublewords (wrap) | mm, mm/mem64
PSUBSB | Subtract packed bytes with signed saturation | mm, mm/mem64
PSUBSW | Subtract packed words with signed saturation | mm, mm/mem64
PSUBUSB | Subtract packed bytes with unsigned saturation | mm, mm/mem64
PSUBUSW | Subtract packed words with unsigned saturation | mm, mm/mem64
PMULLW | Multiply packed words (low 16 bits of product) | mm, mm/mem64
PMULHW | Multiply packed words (high 16 bits of product) | mm, mm/mem64
PMULHUW | Multiply packed unsigned words (high 16 bits) | mm, mm/mem64
PMADDWD | Multiply and add packed words to doublewords | mm, mm/mem64

Comparison

Mnemonic | Description | Operands
PCMPEQB | Compare packed bytes for equality | mm, mm/mem64
PCMPEQW | Compare packed words for equality | mm, mm/mem64
PCMPEQD | Compare packed doublewords for equality | mm, mm/mem64
PCMPGTB | Compare packed bytes for greater than (signed) | mm, mm/mem64
PCMPGTW | Compare packed words for greater than | mm, mm/mem64
PCMPGTD | Compare packed doublewords for greater than | mm, mm/mem64

Logical

Mnemonic | Description | Operands
PAND | Bitwise AND | mm, mm/mem64
PANDN | Bitwise AND-NOT | mm, mm/mem64
POR | Bitwise OR | mm, mm/mem64
PXOR | Bitwise XOR | mm, mm/mem64

Shift

Mnemonic | Description | Operands
PSLLW | Pack shift left logical words | mm, imm8/mm
PSLLD | Pack shift left logical doublewords | mm, imm8/mm
PSLLQ | Pack shift left logical quadword | mm, imm8/mm
PSRLW | Pack shift right logical words | mm, imm8/mm
PSRLD | Pack shift right logical doublewords | mm, imm8/mm
PSRLQ | Pack shift right logical quadword | mm, imm8/mm
PSRAW | Pack shift right arithmetic words | mm, imm8/mm
PSRAD | Pack shift right arithmetic doublewords | mm, imm8/mm

Pack / Unpack

Mnemonic | Description | Operands
PACKSSWB | Pack signed words to bytes (saturated) | mm, mm/mem64
PACKSSDW | Pack signed doublewords to words (saturated) | mm, mm/mem64
PACKUSWB | Pack unsigned words to bytes (unsigned sat.) | mm, mm/mem64
PUNPCKHBW | Unpack high bytes (interleave) | mm, mm/mem64
PUNPCKHWD | Unpack high words | mm, mm/mem64
PUNPCKHDQ | Unpack high doublewords | mm, mm/mem64
PUNPCKLBW | Unpack low bytes | mm, mm/mem64
PUNPCKLWD | Unpack low words | mm, mm/mem64
PUNPCKLDQ | Unpack low doublewords | mm, mm/mem64

Conversion

Mnemonic | Description | Operands
PACKSSWB | Pack words to bytes (saturated) | mm, mm/mem64
PACKSSDW | Pack doublewords to words (saturated) | mm, mm/mem64
PACKUSWB | Pack words to bytes (unsigned saturated) | mm, mm/mem64
PMOVMSKB | Move byte mask to GPR (MSB of each byte) | reg, mm

State Management

Mnemonic | Description
EMMS | Empty MMX state (clear MMX/x87 tag word)
FEMMS | Fast EMMS (AMD, clears fewer registers)

MMX Examples

; Add 8 bytes with saturation
movq    mm0, [byte_array_a]
movq    mm1, [byte_array_b]
paddusb mm0, mm1          ; unsigned saturated add
movq    [result], mm0

; Compare two 16-bit vectors
movq    mm0, [vector_a]
movq    mm1, [vector_b]
pcmpeqw mm0, mm1          ; word-wise equality
movq    [result], mm0

; Calculate sum of absolute differences
movq    mm0, [block_a]
movq    mm1, [block_b]
psadbw  mm0, mm1         ; sum of absolute differences -> low qword
movd    eax, mm0         ; result in eax

; Always clear MMX state before FPU
emms                     ; important!


x87 FPU Mnemonics

The x87 floating-point unit provides 80-bit extended-precision arithmetic. PBXA64 supports the full x87 instruction set. The x87 has 8 registers (ST0-ST7) organised as a stack, and supports single (32-bit), double (64-bit), and extended (80-bit) precision.

Note: On modern x64 processors, prefer SSE instructions for scalar floating-point. The x87 is primarily used for extended precision (80-bit) calculations or for legacy code compatibility.

Data Transfer

Mnemonic | Description | Operands
FLD | Load real value onto stack (push) | mem32/64/80 / ST(i)
FST | Store real value (pop = FSTP) | mem32/64 / ST(i)
FSTP | Store real value and pop | mem32/64/80 / ST(i)
FILD | Load integer value onto stack (push) | mem16/32/64
FIST | Store integer value | mem16/32
FISTP | Store integer value and pop | mem16/32/64
FISTTP | Truncate and store integer, pop (SSE3) | mem16/32/64
FBLD | Load BCD value (18-digit packed BCD) | mem80 (TBYTE)
FBSTP | Store BCD value and pop | mem80 (TBYTE)
FXCH | Exchange ST(0) with ST(i) | ST(i)
; Load constants
fld     [double_var]       ; push 64-bit value
fild    [int_val]          ; push integer converted to float
fldz                       ; push +0.0
fld1                       ; push +1.0
fldpi                      ; push pi
fldl2t                     ; push log2(10)
fldl2e                     ; push log2(e)
fldlg2                     ; push log10(2)
fldln2                     ; push ln(2)

; Store results
fstp    [result]           ; pop and store to memory

Basic Arithmetic

Mnemonic | Description | Operands
FADD | Add (ST0 = ST0 + src) | mem32/64 / ST(i)
FADDP | Add and pop (ST(i) = ST(i)+ST0, then pop) | ST(i), ST(0)
FIADD | Add integer to ST0 | mem16/32
FSUB | Subtract (ST0 = ST0 - src) | mem32/64 / ST(i)
FSUBP | Subtract and pop | ST(i), ST(0)
FSUBR | Subtract reverse (ST0 = src - ST0) | mem32/64 / ST(i)
FSUBRP | Subtract reverse and pop | ST(i), ST(0)
FISUB | Subtract integer | mem16/32
FMUL | Multiply (ST0 = ST0 * src) | mem32/64 / ST(i)
FMULP | Multiply and pop | ST(i), ST(0)
FIMUL | Multiply by integer | mem16/32
FDIV | Divide (ST0 = ST0 / src) | mem32/64 / ST(i)
FDIVP | Divide and pop | ST(i), ST(0)
FDIVR | Divide reverse (ST0 = src / ST0) | mem32/64 / ST(i)
FDIVRP | Divide reverse and pop | ST(i), ST(0)
FIDIV | Divide by integer | mem16/32
FPREM | Partial remainder | none
FPREM1 | Partial remainder (IEEE) | none
FABS | Absolute value | none
FCHS | Change sign (negate) | none
FRNDINT | Round to integer (current rounding mode) | none
FSQRT | Square root | none
FSCALE | Scale by power of 2 (ST0 * 2^ST1) | none
FXTRACT | Extract exponent and significand | none
; Compute: result = sqrt(a*a + b*b)
fld     [a]                ; ST0 = a
fmul    ST0, ST0           ; ST0 = a^2
fld     [b]                ; ST0 = b, ST1 = a^2
fmul    ST0, ST0           ; ST0 = b^2, ST1 = a^2
faddp   ST1, ST0           ; ST0 = a^2 + b^2
fsqrt                      ; ST0 = sqrt(a^2 + b^2)
fstp    [result]           ; store result, pop

Comparison

Mnemonic | Description | Operands
FCOM | Compare ST0 with src (sets FPU status word C0/C2/C3) | mem32/64 / ST(i)
FCOMP | Compare and pop | mem32/64 / ST(i)
FCOMPP | Compare and pop twice | none
FICOM | Compare ST0 with integer | mem16/32
FICOMP | Compare integer and pop | mem16/32
FCOMI | Compare and set EFLAGS (P6+, ST0 with ST[i]) | ST(i)
FCOMIP | Compare, set EFLAGS, and pop | ST(i)
FUCOMI | Unordered compare, set EFLAGS | ST(i)
FUCOMIP | Unordered compare, set EFLAGS, pop | ST(i)
FUCOM | Unordered compare (no exception on NaN) | ST(i)
FUCOMP | Unordered compare and pop | ST(i)
FUCOMPP | Unordered compare and pop twice | none
FTST | Test ST0 against 0.0 | none
FXAM | Examine ST0 (NaN, normal, denormal, zero, etc.) | none
; Compare ST0 with ST1
fcom    ST1                ; compare, sets FPU flags
fstsw   ax                 ; store FPU status word to AX
sahf                       ; load AH into EFLAGS
jae     above_or_equal

; Compare using FCOMI (direct EFLAGS)
fcomi   ST0, ST1           ; sets ZF/PF/CF directly
jb      below
je      equal
ja      above

Constants

Mnemonic | Description | Pushed Value
FLDZ | Load +0.0 | +0.0
FLD1 | Load +1.0 | +1.0
FLDPI | Load pi (π) | 3.14159265358979324
FLDL2E | Load log2(e) | 1.44269504088896341
FLDLN2 | Load ln(2) | 0.69314718055994531
FLDL2T | Load log2(10) | 3.32192809488736235
FLDLG2 | Load log10(2) | 0.30102999566398120

Trigonometric / Transcendental

Mnemonic | Description
FSIN | Sine of ST0 (ST0 in radians)
FCOS | Cosine of ST0
FSINCOS | Sine and cosine of ST0 (ST1=sin, ST0=cos)
FPTAN | Partial tangent (ST1=tan, ST0=1.0)
FPATAN | Partial arctangent (ST1/ST0 → ST1=atan, pop)
F2XM1 | 2^ST0 - 1
FYL2X | ST1 * log2(ST0), pop
FYL2XP1 | ST1 * log2(ST0 + 1), pop
; Compute sin(x)
fld     [x]
fsin                       ; ST0 = sin(x)
fstp    [result]           ; store

; Compute x * log2(y)
fld     [y]
fld     [x]
fyl2x                      ; ST0 = x * log2(y)
fstp    [result]

; Compute 2^x - 1
fld     [x]
f2xm1                      ; ST0 = 2^x - 1
fstp    [result]

Control / Status

Mnemonic | Description | Operands
FNCLEX | Clear FPU exceptions (no wait) | none
FCLEX | Clear FPU exceptions (wait) | none
FNINIT | Initialize FPU (no wait) | none
FINIT | Initialize FPU (wait) | none
FSTSW | Store FPU status word | mem16 / AX
FSTCW | Store FPU control word | mem16
FLDCW | Load FPU control word | mem16
FSTENV | Store FPU environment | mem (14/28 bytes)
FLDENV | Load FPU environment | mem
FSAVE | Save FPU state (94/108 bytes) | mem
FRSTOR | Restore FPU state | mem
FINCSTP | Increment FPU stack pointer | none
FDECSTP | Decrement FPU stack pointer | none
FFREE | Free FPU register ST(i) | ST(i)
FNOP | FPU no operation | none
FWAIT | Wait for FPU (assembly: WAIT) | none

FPU Control Word

The FPU control word controls precision, rounding mode, and exception masks:

Bit(s) | Field | Values
1:0 | Rounding Control | 00=nearest, 01=down, 10=up, 11=truncate
3:2 | Precision Control | 00=24-bit(single), 10=53-bit(double), 11=64-bit(extended)
5 | Exception: Precision | 0=masked, 1=unmasked
6 | Exception: Underflow |
7 | Exception: Overflow |
8 | Exception: Zero Divide |
9 | Exception: Denormal |
10 | Exception: Invalid |
; Set rounding to truncate (toward zero)
fstcw  [cw]               ; save current control word
mov    ax, [cw]
or     ax, 0x0C00         ; set RC bits to 11 (truncate)
mov    [cw_new], ax
fldcw  [cw_new]           ; load new control word


Cache Control / Prefetch Mnemonics

Cache Control & Prefetch Instructions

Instructions for cache hierarchy management, prefetching, non-temporal stores, and memory ordering barriers.

Prefetch Instructions

Mnemonic | Description | Operands
PREFETCHh | Prefetch data into cache at specified hint level | mem8
PREFETCHNTA | Prefetch into L1 data cache (non-temporal, minimal pollution) | mem8
PREFETCHT0 | Prefetch into all cache levels (L1, L2, L3) | mem8
PREFETCHT1 | Prefetch into L2 and L3 (not L1) | mem8
PREFETCHT2 | Prefetch into L3 only | mem8
PREFETCHW | Prefetch for write (reduce RFO latency, AMD/Intel) | mem8
PREFETCHWT1 | Prefetch for write into L2 (AVX-512) | mem8
; Prefetch data for read-intensive processing
prefetcht0 [rsi+64]       ; start loading cache line into L1
prefetcht1 [rsi+128]      ; prefetch into L2
prefetchnta [rsi+192]     ; non-temporal (don't pollute caches)

; Prefetch for write
prefetchw [rdi+64]        ; hint: we'll write here soon

Cache Line Flush / Writeback

Mnemonic | Description | Operands
CLFLUSH | Flush cache line containing address (writeback + invalidate) | mem8
CLFLUSHOPT | Flush cache line (optimized, buffered) | mem8
CLWB | Cache line write back (retain in cache if still needed) | mem8
CLZERO | Zero cache line (AMD only, clears 64 bytes) | none (uses [rax address])
CLDEMOTE | Demote cache line from L1 to lower levels (L2/L3) | mem8
; Write-back and flush a cache-aligned buffer
clflushopt [rdi]           ; optimized cache line flush
clwb       [rdi]           ; write-back but keep in cache

; Memory-mapped I/O: ensure write is visible to device
mov    DWORD PTR [mmio_reg], eax
clflush [mmio_reg]         ; flush write from cache to memory

Non-Temporal (Streaming) Stores

Non-temporal stores bypass the cache and write directly to memory, avoiding cache pollution. Ideal for large data structures written once.

Mnemonic | Description | Operands
MOVNTI | Non-temporal store of integer (dword/qword) | mem32/64, reg
MOVNTDQ | Non-temporal store of 128 bits (SSE2) | mem128, xmm
MOVNTDQA | Non-temporal load (streaming load hint, SSE4.1) | xmm, mem128
MOVNTPD | Non-temporal store of packed double (SSE2) | mem128, xmm
MOVNTPS | Non-temporal store of packed single (SSE) | mem128, xmm
VMOVNTDQ | VEX non-temporal 128/256-bit store (AVX) | mem, ymm/xmm
VMOVNTPD | VEX non-temporal double store (AVX) | mem, ymm/xmm
VMOVNTPS | VEX non-temporal single store (AVX) | mem, ymm/xmm
VMOVNTDQA | VEX non-temporal load (AVX2) | ymm/xmm, mem
; Non-temporal memory copy (large blocks)
; AVX variant - streaming store avoids cache pollution
vmovntdq [rdi],   ymm0    ; write 32 bytes, bypass cache
vmovntdq [rdi+32], ymm1   ; next 32 bytes
; ... use sfence to ensure visibility
sfence

; Non-temporal integer store (for single values)
movnti [rdi], eax          ; atomic 32-bit streaming store
movnti [rdi], rax          ; 64-bit streaming store

Memory Barriers & Fences

Mnemonic | Description
SFENCE | Store fence (serializes all store operations)
LFENCE | Load fence (serializes all load operations)
MFENCE | Memory fence (serializes all load and store operations)
SFENCE | Store fence (ensures all previous stores are globally visible)
LFENCE | Load fence (ensures all previous loads complete before next load)
; Memory ordering: producer-consumer
; Thread 1 (producer):
mov    DWORD PTR [data], eax
sfence                       ; ensure data visible before flag
mov    DWORD PTR [flag], 1

; Thread 2 (consumer):
spin:
    mov    eax, DWORD PTR [flag]
    lfence                   ; ensure flag loaded before data
    test   eax, eax
    jz     spin
    mov    ebx, DWORD PTR [data]

; Full memory barrier (both loads and stores)
lock or DWORD PTR [rsp], 0  ; alternative full barrier
; or simply:
mfence

Cache Control Usage Patterns

Streaming Copy (memcpy with NT stores)

; Copy 4096 bytes with non-temporal stores
mov    ecx, 128             ; 4096 / 32 (256-bit)
mov    rsi, src
mov    rdi, dst
loop:
    vmovdqa ymm0, [rsi]
    vmovntdq [rdi], ymm0
    add    rsi, 32
    add    rdi, 32
    dec    ecx
    jnz    loop
sfence                       ; ensure all NT stores are visible
vzeroupper

Cache Line Flush for NVDIMM Persistency

; Ensure data is persistent on NVDIMM
mov    DWORD PTR [journal], eax
clwb   [journal]            ; write-back cache line
sfence                       ; order CLWB before next barrier
; ... optionally wait for PCOMMIT (older platforms) ...
; With Intel eADR, CLWB + SFENCE is sufficient for persistency

Prefetch for Strided Access Patterns

; Strided matrix access (column-major)
xor    ecx, ecx
loop_col:
    prefetcht0 [rsi+rdx*8]   ; prefetch column element
    movsd  xmm0, [rsi]
    addsd  xmm0, [rdi+rcx]
    movsd  [rsi], xmm0
    add    rsi, rdx           ; stride
    inc    ecx
    cmp    ecx, 64
    jb     loop_col

Instruction Summary by Hint Level

Instruction | Cache Impact | Use Case
PREFETCHNTA | L1 only, non-temporal | Data read once, minimize L2/L3 pollution
PREFETCHT0 | L1, L2, L3 | Data accessed multiple times soon
PREFETCHT1 | L2, L3 (skip L1) | Data accessed soon but not immediately
PREFETCHT2 | L3 only | Data accessed in near future
PREFETCHW | All levels, exclusive | Data to be written (exclusive state)
MOVNT* | Bypass cache (write-combining) | Large streaming writes (framebuffer, large buffers)
CLFLUSH | Flush+invalidate cache line | Cache-coherent DMA, persistency
CLFLUSHOPT | Flush (buffered, faster) | Same as CLFLUSH but higher throughput
CLWB | Write-back (retain cache) | NVDIMM persistency, retains line in cache
CLDEMOTE | Move from L1 to L2/L3 | Reduce L1 pressure for data not immediately needed


PBXA64 Compiler Help — Command Index

PBXA64 is a native x86-64 compiler for the PowerBASIC language, producing optimised PE32+ executables for Windows x64. It supports multiple front-end dialects — PowerBASIC, inline assembler (#ASM), C (#CCODE), and PILOT (#PCODE) — together with a rich standard library of built-in functions and statements. Use the index below to navigate the command reference.

  • String Functions
  • Math / Numeric Functions
  • Type Conversion
  • Control Flow
  • Error Handling
  • File I/O
  • Data / READ / RESTORE
  • Array Operations
  • Declaration / Variables / Types
  • Memory / Pointer
  • Console / Text I/O
  • Threading
  • GUI / DDT / Graphics
  • Networking (TCP/UDP)
  • Compiler Directives
  • Miscellaneous
  • PILOT Frontend (#PCODE)

String Functions

LEN STRPTR VARPTR TRIM$ LTRIM$ RTRIM$ UCASE$ LCASE$ REPEAT$ STRDELETE$ STRINSERT$ STRREVERSE$ TALLY VERIFY SCAN BIN$ OCT$ HEX$ TAB$ REPLACE$ LEFT$ RIGHT$ MID$ SPACE$ INSTR STR$ CHR$ ASC STRING$ FORMAT$ VAL DIR$ COMMAND$ ENVIRON$ CURDIR$ ASCW PARSECOUNT MATCH LSET RSET SPLIT JOIN$

Math / Numeric Functions

ABS SGN INT FIX FRAC MIN MAX CLAMP SIN COS TAN ATN EXP LOG SQR LOG2 LOG10 ROUND RND POW TIMER IIF CHOOSE SWITCH

Type Conversion

CINT CLNG CSNG CDBL VALI VALD MKBYT$ MKI$ MKL$ MKDWD$ MKQ$ MKS$ MKD$ CVBYT CVI CVL CVDWD CVQ CVS CVD

Control Flow

IF / THEN / ELSE SELECT CASE FOR / NEXT WHILE / WEND DO / LOOP GOTO GOSUB / RETURN EXIT ITERATE CALL LABEL

Error Handling

ON ERROR ERROR RESUME ERRCLEAR TRY / CATCH THROW ERR ERL

File I/O

OPEN CLOSE RESET PRINT # WRITE # INPUT # LINE INPUT # GET # PUT # SEEK FLUSH SETEOF LOF EOF LOC FREEFILE KILL NAME FILECOPY MKDIR CHDIR RMDIR SETATTR GETATTR

Data / READ / RESTORE

DATA READ RESTORE

Array Operations

DIM REDIM ERASE ARRAY ASSIGN ARRAY SORT ARRAY SCAN ARRAY REVERSE ARRAY COPY ARRAY DELETE ARRAY INSERT LBOUND UBOUND

Declaration / Variables / Types

LOCAL GLOBAL STATIC SHARED THREADED CONST ENUM TYPE / END TYPE UNION DECLARE EXPORT MODULE INTERFACE BYTE WORD INTEGER DWORD LONG QUAD SINGLE DOUBLE STRING WSTRING VARIANT

Memory / Pointer

ALLOCATE CALLOC REALLOCATE FREE PEEK POKE CODEPTR FUNCPTR

Console / Text I/O

PRINT INPUT LINE INPUT LOCATE CLS COLOR WIDTH BEEP LPRINT

Threading

THREAD CREATE THREAD CLOSE THREAD STATUS THREAD SUSPEND THREAD RESUME THREADCOUNT XLAUNCH WAITFOR

GUI / DDT / Graphics

DIALOG NEW DIALOG SHOW DIALOG CLOSE DIALOG SET TEXT DIALOG GET TEXT DIALOG ENABLE DIALOG SEND DIALOG POST CONTROL ADD CONTROL SET TEXT CONTROL GET TEXT CONTROL SET STATE CONTROL GET STATE MENU NEW MENU ADD MENU ATTACH MENU SHOW POPUP GRAPHIC WINDOW GRAPHIC LINE GRAPHIC BOX GRAPHIC CIRCLE GRAPHIC SET GRAPHIC GET GRAPHIC CLEAR GRAPHIC PRINT GRAPHIC COLOR

Networking (TCP/UDP)

TCP OPEN TCP CLOSE TCP SEND TCP RECV TCP ACCEPT TCP NOTIFY TCP LINE INPUT TCP PRINT UDP OPEN UDP CLOSE UDP SEND UDP RECV

Compiler Directives

#INCLUDE #COMPILE #DIM ALL #OPTIMIZE #STACK #ALIGN #DEBUG #ASM #CCODE #PCODE #OVERRIDE #IF

Miscellaneous

SLEEP SHELL RANDOMIZE SWAP INCR / DECR

PILOT Frontend (#PCODE)

PILOT A: PILOT C: PILOT E: PILOT J: PILOT M: PILOT N: PILOT R: PILOT T: PILOT U: PILOT Y:


PBXA64 Compiler Features

Version 0.65.0-B25 — x86-64 Windows multi-language compiler

Frontend Languages

PowerBASIC (.pb, .bas, .pbi, .inc)

Full PB syntax: #DIM ALL, DECLARE/LIB/ALIAS, FUNCTION PBMAIN, SUB/FUNCTION, LOCAL/GLOBAL/SHARED/STATIC, TYPE/UNION/ENUM, MACRO/MACROFUNCTION, #INCLUDE, conditional compilation, #ASM/#CCODE/#PCODE directives.

C (via #CCODE / #ENDC)

C-style lexing/parsing: struct/union/typedef/enum/pointer/array, extern function declarations, initializers.

PILOT (via #PCODE / #ENDP)

Educational PILOT language: T:/A:/M:/Y:/N:/J:/U:/E: commands, conditional suffixes, pattern matching.

Inline Assembler (#ASM / #ENDASM)

Intel-syntax x64 blocks with CLOBBER/UNSAFE/ALLOW_PRIVILEGED, variable binding (%var, {var}), ASMDATA directives.

Data Types

Type | Size | Description
BYTE | 1 | Unsigned 8-bit
WORD | 2 | Unsigned 16-bit
INTEGER | 2 | Signed 16-bit
DWORD | 4 | Unsigned 32-bit
LONG | 4 | Signed 32-bit
QUAD | 8 | Signed 64-bit
SINGLE | 4 | IEEE 754 32-bit float
DOUBLE | 8 | IEEE 754 64-bit float
STRING | 16 | Dynamic descriptor (ptr + len)
WSTRING | 16 | UTF-16 descriptor
VARIANT | 16 | COM VARIANT
Pointer types | 8 | BYTE PTR, WORD PTR, etc.

PB Language Features

Control Flow

IF/THEN/ELSE/ELSEIF/END IF, SELECT CASE, FOR/NEXT, WHILE/WEND, DO/LOOP, GOTO, GOSUB/RETURN, EXIT/ITERATE, ON ERROR/RESUME, DATA/READ/RESTORE.

String Builtins (44+)

LEN, STRPTR, VARPTR, TRIM$, LTRIM$, RTRIM$, UCASE$, LCASE$, REPEAT$, STRDELETE$, STRINSERT$, STRREVERSE$, BIN$, OCT$, HEX$, REPLACE$, TALLY, VERIFY, SCAN$, MID$, LEFT$, RIGHT$, SPACE$, CHR$, ASC, VAL, STR$, FORMAT$, BUILD$, CLIP$, RETAIN$, SHRINK$, NUL$, DEC$, MKI$/MKL$/MKQ$/MKS$/MKD$, CVI/CVL/CVQ/CVS/CVD, JOIN$, SPLIT, PEEK$, INPUT$, INKEY$, WAITKEY$, COMMAND$, ENVIRON$, CURDIR$, TAB$.

Math Builtins

ABS, MIN, MAX, CLAMP, INT, FIX, SGN, FRAC, SIN/COS/TAN/ATN/SQR/EXP/LOG, RND/RANDOMIZE, ROUND.

Arrays

Fixed arrays (DIM a(100)), dynamic-style (DIM a() + REDIM), LBOUND/UBOUND, ARRAY ASSIGN/SORT/COPY/SCAN/REVERSE.

File I/O

OPEN (OUTPUT/APPEND/INPUT/RANDOM/BINARY), CLOSE, PRINT #, INPUT #, LINE INPUT #, GET/PUT, SEEK, LOF/EOF/LOC, KILL, NAME, MKDIR, CHDIR, DIR$, FILECOPY, RMDIR, GETATTR/SETATTR, FREEFILE.

Threading, COM, GUI, Networking

  • Threading: THREAD FUNCTION, XLAUNCH, WAITFOR
  • COM/OOP: CLASS vtables, IUnknown, CoCreateInstance
  • GUI / DDT: DIALOG NEW, CONTROL ADD, GRAPHIC WINDOW, menu system
  • Networking: TCP/UDP OPEN/SEND/RECV

Compilation Pipeline

Stage | Description
Driver | CLI parsing, file discovery
Preprocessor | Macro expansion, #INCLUDE, conditional compilation
Lexer | Tokenization
Parser | AST construction (recursive-descent)
Semantic | Type checking, symbol resolution, #DIM ALL
IR | PB HIR to MGC IR bridge
Optimizer | 20+ optimization passes
Codegen | Instruction selection, register allocation, MIR
Assembler | Intel-syntax encoding, COFF output
Linker | Object merge, symbol resolution, PE32+ write

Optimization Passes

Constant Folding, Dead Code Elimination, Mem2Reg, Copy Propagation, CFG Cleanup, Strength Reduction, Instruction Combining, Branch Simplification, SCCP, GVN, Dead Store Elimination, ADCE, Reassociation, Load Forwarding, SROA, Inlining, LICM, FMA Contraction, Vectorization, Profile-Guided Optimization.

Assembler

408+ mnemonics across 10 ISA families: Core GPR (~400), SSE/SSE2/SSE3/SSSE3/SSE4 (~300), AVX/AVX2/AVX-512/FMA (~500), BMI1/BMI2 (~16), AES-NI/SHA/Crypto (~25), System (~50), SGX/VMX/CET (~40), MMX (~60), x87 FPU (~80), Cache/Prefetch (~20).

x64 GPRs (8/16/32/64-bit), XMM registers, 6 addressing modes, 21 operand variants, segment overrides.

Linker (PE32+)

COFF object merge, static library archive extraction, symbol resolution (weak/strong), relocation processing (ADDR64/REL32/SECREL), import table, PE32+ headers, TLS/load-config/exception directories, debug directory + CodeView, base relocations, DLL export table, resources, post-link optimization (DCE/ICF/strip), LTO, PE verification.

Command-Line

-o output, -c compile only, -S assembly only, -E preprocess, /exe//dll, -O0 to -O3 optimization, --pgo-generate/--pgo-use, --flto, -g debug info, -v verbose, --dump-tokens/--dump-ast/--dump-ir, -Wall/-Wextra/-Werror, --diagnostic-format (text/json/sarif).

Test Coverage

110/110 CTest tests passing: frontend (PB lexer, parser, HIR bridge), C frontend, middle-end (CFG, SSA, optimizer), backend (ABI, ISEL, regalloc), assembler, linker, driver, runtime suite, negative suite, ASM mnemonics suite.


LEN - PBXA64 Compiler Help

LEN

Returns the number of characters in a string expression.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

n& = LEN(str)

Description

LEN returns the current length of a string as a LONG integer. For PB_STRING64 descriptors, the length is stored directly in the descriptor's len field, making this a constant-time operation. An uninitialized or empty string returns zero. LEN can also be used with non-string types (numeric, UDT) to return the byte size of the variable, though the string form is the primary use case.

Parameters

str — any string expression, variable, or string literal.

Return Value

A LONG integer containing the number of characters in the string.

Parameters

Name | Description
str | String expression to measure. Can be a string variable, literal, or expression returning a string.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL n AS LONG
s = "Hello, World!"
n = LEN(s)       ' n = 13
n = LEN("ABC")   ' n = 3
n = LEN("")      ' n = 0

Assembler Output

The compiler generates the following x64 code for LEN on a PB_STRING64 descriptor:

; PBXA64 x64 assembly for LEN(str)
; Assume str is a PB_STRING64 descriptor at [rbp-32]
mov rax, [rbp-32]        ; load PB_STRING64 struct pointer
mov rax, [rax+8]         ; read len field (offset 8 in descriptor)
mov [rbp-8], rax         ; store result in n

See Also

  • STRPTR
  • VARPTR
  • ASC

Back to command index


STRPTR - PBXA64 Compiler Help

STRPTR

Returns the memory address of the character data underlying a PB_STRING64 variable.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

p& = STRPTR(str)

Description

STRPTR returns a LONG pointer to the first byte of the string's character buffer. The PB_STRING64 descriptor is a 24-byte structure: [data_ptr (8), length (8), capacity (8)]. STRPTR reads the first QWORD, which points to the heap-allocated or static character array. This is useful for passing string data to external API functions that expect a C-style char pointer, or for low-level memory operations. The returned pointer is valid only while the string variable exists; re-assigning or modifying the string may reallocate the buffer.

Parameters

str — a string variable (not a literal or expression, though the compiler may accept these).

Return Value

A LONG (64-bit pointer) to the string's character buffer.

Parameters

Name | Description
str | String variable whose data pointer is requested. Must be a string-type variable.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL p AS LONG
s = "Hello"
p = STRPTR(s)       ' p contains address of 'H' character buffer

Assembler Output

The compiler reads the data_ptr field (offset 0) from the PB_STRING64 descriptor:

; PBXA64 x64 assembly for STRPTR(str)
mov rax, [rbp-32]        ; load PB_STRING64 descriptor
mov rax, [rax]           ; read data_ptr field (offset 0)
mov [rbp-8], rax         ; store pointer result

See Also

  • LEN
  • VARPTR
  • ASC


VARPTR - PBXA64 Compiler Help

VARPTR

Returns the memory address of a variable's descriptor or storage location.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

p& = VARPTR(variable)
p& = VARPTR(array(sub1, sub2))

Description

VARPTR returns the address of the variable's storage. For simple numeric variables, this is the address of the value itself on the stack or in the data section. For string variables, this is the address of the PB_STRING64 descriptor (a 24-byte structure containing data pointer, length, and capacity). For array variables, VARPTR returns the address of the array descriptor, which contains metadata about dimensions and element size. Use VARPTR to pass variables to external API functions that require pointer arguments or to perform low-level memory inspection.

Parameters

variable — any variable, array element, or TYPE/UDT field.

Return Value

A LONG (64-bit pointer) to the variable's stack or data location.

Parameters

Name | Description
variable | Any variable, array element, or UDT field. For string variables, returns address of the descriptor.

Examples

#DIM ALL
LOCAL x AS LONG
LOCAL s AS STRING
LOCAL p AS LONG
x = 42
p = VARPTR(x)        ' p = address of x on stack
s = "Test"
p = VARPTR(s)        ' p = address of PB_STRING64 descriptor for s

Assembler Output

The compiler emits a LEA instruction to compute the variable's stack address:

; PBXA64 x64 assembly for VARPTR(x)
lea rax, [rbp-8]         ; address of x on the stack
mov [rbp-16], rax        ; store pointer result

See Also

  • STRPTR
  • CODEPTR
  • LEN


TRIM$ - PBXA64 Compiler Help

TRIM$

Removes leading and trailing whitespace characters from a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = TRIM$(str)

Description

TRIM$ returns a new string with all leading and trailing whitespace (spaces, tabs) removed. The runtime helper __pb_trim scans forward from the start of the string and backward from the end to find the first and last non-whitespace characters, then creates a new PB_STRING64 descriptor that references a substring of the original buffer. No heap allocation occurs when trimming within the original string's buffer — the new descriptor simply adjusts the data pointer and length. If the string is entirely whitespace, an empty string is returned.

Parameters

str — string expression to trim.

Return Value

A string with all leading and trailing whitespace removed.

Parameters

Name | Description
str | String expression to remove surrounding whitespace from.

Examples

#DIM ALL
LOCAL s AS STRING
s = TRIM$("   Hello   ")     ' s = "Hello"
s = TRIM$("  ")              ' s = "" (empty)
s = TRIM$("NoSpaces")        ' s = "NoSpaces"

Assembler Output

The compiler emits a call to the trim runtime helper:

; PBXA64 x64 assembly for TRIM$(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_trim           ; returns trimmed descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • LTRIM$
  • RTRIM$
  • UCASE$


LTRIM$ - PBXA64 Compiler Help

LTRIM$

Removes leading (left-side) whitespace or specified characters from a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = LTRIM$(str)
s$ = LTRIM$(str, chars)

Description

LTRIM$ removes characters from the beginning of a string. Without the second argument, it removes all leading whitespace (spaces and tabs). With the optional chars argument, it removes any leading characters that appear in the charset string. The runtime helper __pb_ltrim scans forward from the start, comparing each byte against the character set, and creates a new descriptor pointing to the first non-matching character. The length field is adjusted accordingly.

Parameters

str — string expression to process.
chars — optional string containing the set of characters to remove.

Return Value

A string with leading characters removed.

Parameters

Name | Description
str | String expression to left-trim.
chars (opt) | Character set to remove. Defaults to whitespace if omitted.

Examples

#DIM ALL
LOCAL s AS STRING
s = LTRIM$("   Hello")       ' s = "Hello"
s = LTRIM$("...Hello", ".")  ' s = "Hello"
s = LTRIM$("xxHello", "x")   ' s = "Hello"

Assembler Output

The compiler calls __pb_ltrim with the string descriptor and optional charset:

; PBXA64 x64 assembly for LTRIM$(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_ltrim          ; returns trimmed descriptor in RAX
mov [rbp-64], rax        ; store result

; LTRIM$(str, chars):
mov rcx, [rbp-32]        ; str descriptor
mov rdx, [rbp-64]        ; chars descriptor
call __pb_ltrim          ; returns trimmed descriptor in RAX
mov [rbp-96], rax

See Also

  • TRIM$
  • RTRIM$
  • UCASE$


RTRIM$ - PBXA64 Compiler Help

RTRIM$

Removes trailing (right-side) whitespace or specified characters from a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = RTRIM$(str)
s$ = RTRIM$(str, chars)

Description

RTRIM$ removes trailing characters from the end of a string. Without the second argument, it removes all trailing whitespace. With the optional chars argument, it removes any trailing characters that appear in the charset string. The runtime helper __pb_rtrim scans backward from the end of the string (using the length field) and adjusts the descriptor's length to exclude matching characters. Since PB_STRING64 uses len as the authoritative field, no NUL terminator modification is needed.

Parameters

str — string expression to process.
chars — optional string containing the set of characters to remove.

Return Value

A string with trailing characters removed.

Parameters

Name | Description
str | String expression to right-trim.
chars (opt) | Character set to remove from the end. Defaults to whitespace if omitted.

Examples

#DIM ALL
LOCAL s AS STRING
s = RTRIM$("Hello   ")       ' s = "Hello"
s = RTRIM$("Hello...", ".")  ' s = "Hello"
s = RTRIM$("Hello!!", "!")   ' s = "Hello"

Assembler Output

The compiler calls __pb_rtrim with the string descriptor:

; PBXA64 x64 assembly for RTRIM$(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_rtrim          ; returns trimmed descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • TRIM$
  • LTRIM$
  • UCASE$


UCASE$ - PBXA64 Compiler Help

UCASE$

Converts all lowercase characters in a string to uppercase.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = UCASE$(str)

Description

UCASE$ returns a new string with every lowercase ANSI letter (a-z) converted to its uppercase equivalent (A-Z). Characters outside the a-z range are passed through unchanged. The runtime helper __pb_ucase allocates a new buffer, copies the original string data, and calls CharUpperBuffA (or an inline equivalent) to perform the conversion. The original string is not modified. If the string contains non-ANSI characters (above 127), they are preserved as-is since CharUpperBuffA operates on 8-bit ANSI values.

Parameters

str — string expression to convert to uppercase.

Return Value

A new string with all letters converted to uppercase.

Parameters

Name | Description
str | String expression whose characters are uppercased.

Examples

#DIM ALL
LOCAL s AS STRING
s = UCASE$("Hello World")   ' s = "HELLO WORLD"
s = UCASE$("PowerBASIC")    ' s = "POWERBASIC"
s = UCASE$("123abc!")       ' s = "123ABC!"

Assembler Output

The compiler emits a call to the case conversion helper:

; PBXA64 x64 assembly for UCASE$(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_ucase          ; returns uppercased descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • LCASE$
  • TRIM$
  • STRREVERSE$


LCASE$ - PBXA64 Compiler Help

LCASE$

Converts all uppercase characters in a string to lowercase.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = LCASE$(str)

Description

LCASE$ returns a new string with every uppercase ANSI letter (A-Z) converted to its lowercase equivalent (a-z). Characters outside the A-Z range pass through unchanged. The runtime helper __pb_lcase allocates a new buffer, copies the original data, and calls CharLowerBuffA (or an inline equivalent) for the conversion. As with UCASE$, the original string is never modified. Extension bytes (128-255) and non-alphabetic characters are left untouched.

Parameters

str — string expression to convert to lowercase.

Return Value

A new string with all letters converted to lowercase.

Parameters

Name | Description
str | String expression whose characters are lowercased.

Examples

#DIM ALL
LOCAL s AS STRING
s = LCASE$("Hello World")   ' s = "hello world"
s = LCASE$("POWERBASIC")    ' s = "powerbasic"
s = LCASE$("123ABC!")       ' s = "123abc!"

Assembler Output

The compiler emits a call to the lowercase conversion helper:

; PBXA64 x64 assembly for LCASE$(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_lcase          ; returns lowercased descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • UCASE$
  • TRIM$
  • STRREVERSE$


REPEAT$ - PBXA64 Compiler Help

REPEAT$

Returns a string consisting of a specified number of copies of another string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = REPEAT$(str, n)

Description

REPEAT$ creates a new string by concatenating n copies of str. If n is zero, an empty string is returned. If str is empty, the result is also empty regardless of n. The runtime helper __pb_repeat calculates the total buffer size (LEN(str) * n), allocates a new PB_STRING64 descriptor with a buffer of that size, and copies str into the buffer n times using memcpy in a loop.

Parameters

str — string expression to repeat.
n — number of repetitions (LONG, non-negative).

Return Value

A string containing n concatenated copies of str.

Parameters

Name | Description
str | String expression to repeat.
n | Number of repetitions. Must be 0 or positive.

Examples

#DIM ALL
LOCAL s AS STRING
s = REPEAT$("AB", 3)        ' s = "ABABAB"
s = REPEAT$("Hello ", 2)    ' s = "Hello Hello "
s = REPEAT$("X", 5)         ' s = "XXXXX"
s = REPEAT$("Any", 0)       ' s = "" (empty)

Assembler Output

The compiler calls __pb_repeat with the string and count:

; PBXA64 x64 assembly for REPEAT$(str, n)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
mov rdx, [rbp-8]         ; pass count in RDX
call __pb_repeat         ; returns repeated descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • STRING$
  • SPACE$
  • MID$


STRDELETE$ - PBXA64 Compiler Help

STRDELETE$

Deletes a specified number of characters from a string at a given position.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = STRDELETE$(str, start, len)

Description

STRDELETE$ removes len characters from str beginning at the 1-based start position. The runtime helper __pb_strdelete calculates the total result length (original length minus len), allocates a new buffer, copies the portion before start, then copies the portion after start+len (skipping the deleted region). If len exceeds the available characters from start to end, all characters from start onward are removed. If start is beyond the string length, the original string is returned.

Parameters

str — source string to modify.
start — 1-based position where deletion begins.
len — number of characters to delete.

Return Value

A new string with the specified characters removed.

Parameters

Name | Description
str | Source string expression.
start | 1-based position to start deleting from.
len | Number of characters to delete.

Examples

#DIM ALL
LOCAL s AS STRING
s = STRDELETE$("Hello World", 6, 6)   ' s = "Hello"
s = STRDELETE$("abcdef", 2, 3)        ' s = "aef"
s = STRDELETE$("abc", 1, 1)           ' s = "bc"

Assembler Output

The compiler calls __pb_strdelete with three arguments:

; PBXA64 x64 assembly for STRDELETE$(str, start, len)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-8]         ; pass start in RDX
mov r8, [rbp-16]         ; pass len in R8
call __pb_strdelete      ; returns new descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • STRINSERT$
  • REPLACE$
  • MID$


STRINSERT$ - PBXA64 Compiler Help

STRINSERT$

Inserts one string into another at a specified position.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = STRINSERT$(str, pos, insert$)

Description

STRINSERT$ returns a new string with insert$ placed into str at the 1-based pos position. Characters originally at and after pos are shifted right to make room. The runtime helper __pb_strinsert calculates the total buffer size (LEN(str) + LEN(insert)), allocates a new PB_STRING64 descriptor, copies the portion of str before pos, copies insert$, and then copies the remainder of str after pos. If pos is beyond the end of str, insert$ is appended.

Parameters

str — destination string expression.
pos — 1-based insertion position.
insert$ — string to insert.

Return Value

A new string with insert$ placed at the specified position.

Parameters

Name | Description
str | Source string expression.
pos | 1-based position where insert$ will be placed.
insert$ | String expression to insert.

Examples

#DIM ALL
LOCAL s AS STRING
s = STRINSERT$("Hello World", 6, "Beautiful ")  ' s = "Hello Beautiful World"
s = STRINSERT$("ac", 2, "b")                     ' s = "abc"
s = STRINSERT$("end", 4, "!")                    ' s = "end!"

Assembler Output

The compiler calls __pb_strinsert with three descriptors:

; PBXA64 x64 assembly for STRINSERT$(str, pos, insert$)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-8]         ; pass pos in RDX
mov r8, [rbp-64]         ; pass insert$ descriptor in R8
call __pb_strinsert      ; returns new descriptor in RAX
mov [rbp-96], rax        ; store result

See Also

  • STRDELETE$
  • REPLACE$
  • MID$


STRREVERSE$ - PBXA64 Compiler Help

STRREVERSE$

Reverses the order of characters in a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = STRREVERSE$(str)

Description

STRREVERSE$ returns a new string with all characters in reverse order. The runtime helper __pb_strreverse allocates a new buffer of the same length as the input, then copies characters from the end of the source to the beginning of the destination. The original string is not modified. This is useful for palindrome checks, string mirroring, or any algorithm that needs reversed string content.

Parameters

str — string expression to reverse.

Return Value

A new string with characters in reversed order.

Parameters

Name | Description
str | String expression whose characters will be reversed.

Examples

#DIM ALL
LOCAL s AS STRING
s = STRREVERSE$("Hello")         ' s = "olleH"
s = STRREVERSE$("racecar")       ' s = "racecar" (palindrome)
s = STRREVERSE$("ABC")           ' s = "CBA"

Assembler Output

The compiler calls __pb_strreverse with the string descriptor:

; PBXA64 x64 assembly for STRREVERSE$(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_strreverse     ; returns reversed descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • UCASE$
  • LCASE$
  • MID$


TALLY - PBXA64 Compiler Help

TALLY

Counts the number of non-overlapping occurrences of one string within another.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

n& = TALLY(str, search)

Description

TALLY scans str and counts how many non-overlapping occurrences of search appear. After each match, scanning continues at the position immediately after the match (non-overlapping). This differs from repeatedly calling INSTR in a loop with advancing start positions. TALLY is useful for quickly counting delimiters, word occurrences, or repeated patterns within a string. The runtime helper __pb_tally performs a single forward pass through the string.

Parameters

str — the string to search within.
search — the substring whose occurrences are counted.

Return Value

A LONG containing the number of non-overlapping occurrences of search in str.

Parameters

Name | Description
str | String expression to search within.
search | Substring expression to count.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL n AS LONG
s = "ababab"
n = TALLY(s, "aba")        ' n = 2 (non-overlapping: "aba" at pos 1 and 4)
n = TALLY(s, "ab")         ' n = 3
n = TALLY("Hello World", "o")  ' n = 2

Assembler Output

The compiler calls __pb_tally with both descriptors:

; PBXA64 x64 assembly for TALLY(str, search)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-64]        ; pass search descriptor in RDX
call __pb_tally          ; returns count in RAX
mov [rbp-8], eax         ; store result (LONG)

See Also

  • INSTR
  • VERIFY
  • SCAN


VERIFY - PBXA64 Compiler Help

VERIFY

Returns the position of the first character in a string that is NOT in a specified set of characters.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

p& = VERIFY(str, charset)
p& = VERIFY(str, charset, start)

Description

VERIFY scans str from left to right and returns the 1-based position of the first character that is NOT present in charset. If all characters in str belong to charset, VERIFY returns zero. An optional start parameter specifies where to begin scanning. This is the complement of SCAN, which finds characters that ARE in the set. VERIFY is commonly used to validate input strings (e.g., checking that a string contains only digits).

Parameters

str — string to search.
charset — string containing the set of allowed characters.
start — optional 1-based position to begin scanning.

Return Value

A LONG containing the position of the first non-matching character, or 0 if all characters match the set.

Parameters

Name | Description
str | String expression to scan.
charset | String containing characters that are considered acceptable.
start (opt) | 1-based starting position for the scan. Defaults to 1.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL p AS LONG
s = "12345A"
p = VERIFY(s, "0123456789")  ' p = 6 ('A' is not a digit)
p = VERIFY("12345", "0123456789")  ' p = 0 (all digits)
p = VERIFY("ABC123", "ABC")       ' p = 4 ('1' not in set)

Assembler Output

The compiler calls __pb_verify with the string and charset:

; PBXA64 x64 assembly for VERIFY(str, charset)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-64]        ; pass charset descriptor in RDX
call __pb_verify         ; returns position in RAX
mov [rbp-8], eax         ; store result

; VERIFY(str, charset, start):
mov rcx, [rbp-48]
mov rdx, [rbp-80]
mov r8, [rbp-8]          ; pass start in R8
call __pb_verify
mov [rbp-16], eax

See Also

  • SCAN
  • INSTR
  • TALLY


SCAN - PBXA64 Compiler Help

SCAN

Returns the position of the first character in a string that IS in a specified set of characters.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

p& = SCAN(str, charset)

Description

SCAN searches str for the first occurrence of any character from charset. It returns the 1-based position, or zero if no character from the set is found. This is the complement of VERIFY, which finds characters NOT in the set. SCAN is useful for tokenizing strings, finding delimiters, or locating specific character classes. The runtime helper __pb_scan builds a 256-entry lookup table from the charset for efficient O(n) scanning.

Parameters

str — string to search.
charset — string containing the set of characters to find.

Return Value

A LONG containing the position of the first matching character, or 0 if none found.

Parameters

Name | Description
str | String expression to scan.
charset | String containing characters to locate within str.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL p AS LONG
s = "Hello, World!"
p = SCAN(s, ",")           ' p = 6 (comma found)
p = SCAN(s, "aeiou")       ' p = 2 ('e' is first vowel)
p = SCAN(s, "xyz")         ' p = 0 (none found)

Assembler Output

The compiler calls __pb_scan with both string descriptors:

; PBXA64 x64 assembly for SCAN(str, charset)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-64]        ; pass charset descriptor in RDX
call __pb_scan           ; returns position in RAX
mov [rbp-8], eax         ; store result (LONG)

See Also

  • VERIFY
  • INSTR
  • TALLY


BIN$ - PBXA64 Compiler Help

BIN$

Converts a numeric value to a binary (base-2) string representation.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = BIN$(num)
s$ = BIN$(num, digits)

Description

BIN$ converts an integer numeric value to a string of binary digits ('0' and '1'). If digits is specified, the result is zero-padded on the left to at least that many digits. If the value requires more digits than specified, the full representation is returned without truncation. The runtime helper __pb_bin processes the value from most-significant to least-significant bit, converting each bit to an ASCII '0' or '1'. Negative numbers are represented in two's complement form.

Parameters

num — integer expression to convert.
digits — optional minimum number of binary digits to produce.

Return Value

A string containing the binary representation of num.

Parameters

Name | Description
num | Integer value to convert to binary.
digits (opt) | Minimum digit count for zero-padding.

Examples

#DIM ALL
LOCAL s AS STRING
s = BIN$(42)               ' s = "101010"
s = BIN$(42, 8)            ' s = "00101010"
s = BIN$(255)              ' s = "11111111"
s = BIN$(&b1101)           ' s = "1101" (binary literal input)

Assembler Output

The compiler calls __pb_bin with the value:

; PBXA64 x64 assembly for BIN$(num)
mov rcx, [rbp-8]         ; pass integer value in RCX
call __pb_bin            ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result

; BIN$(num, digits):
mov rcx, [rbp-8]         ; pass value
mov rdx, [rbp-16]        ; pass digit count in RDX
call __pb_bin
mov [rbp-48], rax

See Also

  • OCT$
  • HEX$
  • STR$


OCT$ - PBXA64 Compiler Help

OCT$

Converts a numeric value to an octal (base-8) string representation.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = OCT$(num)
s$ = OCT$(num, digits)

Description

OCT$ converts an integer numeric value to a string of octal digits ('0' to '7'). If digits is specified, the result is zero-padded on the left. The runtime helper __pb_oct groups the binary value into 3-bit chunks starting from the least significant bit and converts each chunk to the corresponding octal digit. Negative numbers are represented in two's complement, producing full 64-bit octal representation for QUAD values (22 digits: 64 bits / 3 = 21.33, rounded up).

Parameters

num — integer expression to convert.
digits — optional minimum number of octal digits to produce.

Return Value

A string containing the octal representation of num.

Parameters

Name | Description
num | Integer value to convert to octal.
digits (opt) | Minimum digit count for zero-padding.

Examples

#DIM ALL
LOCAL s AS STRING
s = OCT$(42)               ' s = "52"
s = OCT$(42, 6)            ' s = "000052"
s = OCT$(255)              ' s = "377"
s = OCT$(&o777)            ' s = "777" (octal literal input)

Assembler Output

The compiler calls __pb_oct with the value:

; PBXA64 x64 assembly for OCT$(num)
mov rcx, [rbp-8]         ; pass integer value in RCX
call __pb_oct            ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result

; OCT$(num, digits):
mov rcx, [rbp-8]
mov rdx, [rbp-16]
call __pb_oct
mov [rbp-48], rax

See Also

  • BIN$
  • HEX$
  • STR$


HEX$ - PBXA64 Compiler Help

HEX$

Converts a numeric value to a hexadecimal (base-16) string representation.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = HEX$(num)
s$ = HEX$(num, digits)

Description

HEX$ converts an integer numeric value to a string of hexadecimal digits ('0'-'9' and 'A'-'F'). If digits is specified, the result is zero-padded on the left to at least that many digits. The runtime helper __pb_hex extracts 4-bit nibbles from the value, converts each to the appropriate hex digit character, and builds the string. For QUAD values, up to 16 hex digits are produced. Negative numbers are represented in two's complement form (producing the full 16-digit hex representation for QUAD).

Parameters

num — integer expression to convert.
digits — optional minimum number of hex digits to produce.

Return Value

A string containing the hexadecimal representation of num.

Parameters

Name | Description
num | Integer value to convert to hexadecimal.
digits (opt) | Minimum digit count for zero-padding.

Examples

#DIM ALL
LOCAL s AS STRING
s = HEX$(255)              ' s = "FF"
s = HEX$(255, 4)           ' s = "00FF"
s = HEX$(3735928559)       ' s = "DEADBEEF"
s = HEX$(&hABC)            ' s = "ABC"

Assembler Output

The compiler calls __pb_hex with the value:

; PBXA64 x64 assembly for HEX$(num)
mov rcx, [rbp-8]         ; pass integer value in RCX
call __pb_hex            ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result

; HEX$(num, digits):
mov rcx, [rbp-8]
mov rdx, [rbp-16]
call __pb_hex
mov [rbp-48], rax

See Also

  • BIN$
  • OCT$
  • STR$


TAB$ - PBXA64 Compiler Help

TAB$

Returns a string of spaces that, when printed, positions the cursor to a specified column.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = TAB$(col)

Description

TAB$ returns a string of space characters (0x20) sufficient to move the print position to column col. The column is 1-based. The runtime helper __pb_tab determines the current print column position (from an internal cursor tracker) and computes how many spaces are needed to reach the target column. If col is less than the current position, TAB$ emits a newline sequence followed by spaces to col. Tab stops are at every 8 columns by default.

Parameters

col — target column number (1-based). Must be positive.

Return Value

A string of spaces that advances the print position to the specified column.

Parameters

Name | Description
col | Target column number (1-based). Typically 1-255.

Examples

#DIM ALL
LOCAL s AS STRING
s = TAB$(10)              ' s = spaces to reach column 10
PRINT "Name:" + TAB$(15) + "Value"
PRINT "Age:" + TAB$(15) + "42"

Assembler Output

The compiler calls __pb_tab with the target column:

; PBXA64 x64 assembly for TAB$(col)
mov rcx, [rbp-8]         ; pass target column in RCX
call __pb_tab            ; returns space string descriptor in RAX
mov [rbp-32], rax        ; store result

See Also

  • SPACE$
  • STRING$
  • LOCATE


REPLACE$ - PBXA64 Compiler Help

REPLACE$

Replaces all occurrences of a substring with another string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = REPLACE$(str, search, replace)

Description

REPLACE$ returns a new string where every non-overlapping occurrence of search in str is replaced with replace. The runtime helper __pb_replace first scans to count occurrences, calculates the required buffer size, allocates a new PB_STRING64 descriptor with the appropriate capacity, and copies the result by alternating between copying literal segments and inserting the replacement string. If search is empty or not found, the original string is returned unchanged.

Parameters

str — source string to process.
search — substring to find and replace.
replace — replacement string.

Return Value

A new string with all occurrences of search replaced by replace.

Parameters

Name | Description
str | Source string expression to modify.
search | Substring to locate within str.
replace | String to substitute for each occurrence of search.

Examples

#DIM ALL
LOCAL s AS STRING
s = REPLACE$("Hello World", "World", "There")  ' s = "Hello There"
s = REPLACE$("ababab", "a", "X")               ' s = "XbXbXb"
s = REPLACE$("Hello", "x", "Y")                ' s = "Hello" (unchanged)

Assembler Output

The compiler calls __pb_replace with three descriptors:

; PBXA64 x64 assembly for REPLACE$(str, search, replace)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-64]        ; pass search descriptor in RDX
mov r8, [rbp-96]         ; pass replace descriptor in R8
call __pb_replace        ; returns new descriptor in RAX
mov [rbp-128], rax       ; store result

See Also

  • STRDELETE$
  • STRINSERT$
  • INSTR


LEFT$ - PBXA64 Compiler Help

LEFT$

Returns the leftmost N characters of a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = LEFT$(str, n)

Description

LEFT$ returns a substring consisting of the first n characters of str. If n is greater than or equal to the length of str, the entire string is returned. If n is zero or negative, an empty string is returned. The runtime helper __pb_left creates a new PB_STRING64 descriptor that shares the original buffer (no copy), adjusting the length field to n. This makes LEFT$ a constant-time operation regardless of string size.

Parameters

str — source string expression.
n — LONG integer specifying the number of characters to take from the left.

Return Value

A string containing the leftmost n characters of str.

Parameters

Name | Description
str | Source string expression to extract from.
n | Number of characters to extract from the left side.

Examples

#DIM ALL
LOCAL s AS STRING
s = LEFT$("PowerBASIC", 5)   ' s = "Power"
s = LEFT$("Hello", 10)       ' s = "Hello" (full string)
s = LEFT$("Hello", 0)        ' s = "" (empty)

Assembler Output

The compiler calls __pb_left with the string and count:

; PBXA64 x64 assembly for LEFT$(str, n)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
mov rdx, [rbp-8]         ; pass n in RDX
call __pb_left           ; returns substring descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • RIGHT$
  • MID$
  • LEN


RIGHT$ - PBXA64 Compiler Help

RIGHT$

Returns the rightmost N characters of a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = RIGHT$(str, n)

Description

RIGHT$ returns a substring consisting of the last n characters of str. If n is greater than or equal to the string length, the entire string is returned. If n is zero or negative, an empty string is returned. The runtime helper __pb_right creates a descriptor pointing into the original buffer at offset (len - n), so it also avoids copying character data. This is a constant-time operation that only manipulates descriptor fields.

Parameters

str — source string expression.
n — LONG integer specifying the number of characters to take from the right.

Return Value

A string containing the rightmost n characters of str.

Parameters

Name | Description
str | Source string expression to extract from.
n | Number of characters to extract from the right side.

Examples

#DIM ALL
LOCAL s AS STRING
s = RIGHT$("PowerBASIC", 4)   ' s = "SIC"
s = RIGHT$("Hello", 3)        ' s = "llo"
s = RIGHT$("Hello", 0)        ' s = "" (empty)

Assembler Output

The compiler calls __pb_right with the string and count:

; PBXA64 x64 assembly for RIGHT$(str, n)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
mov rdx, [rbp-8]         ; pass n in RDX
call __pb_right          ; returns substring descriptor in RAX
mov [rbp-64], rax        ; store result

See Also

  • LEFT$
  • MID$
  • LEN


MID$ - PBXA64 Compiler Help

MID$

Returns a substring starting at a specified position, optionally with a given length.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MID$(str, start)
s$ = MID$(str, start, len)

Description

MID$ extracts a substring from str beginning at the 1-based start position. If only start is given, all characters from start to the end of the string are included. If len is given, at most len characters are returned. Positions beyond the string length result in an empty string. Negative or zero start values are treated as position 1. The runtime helper __pb_mid adjusts the descriptor data pointer by (start-1) and sets length accordingly, with no heap allocation.

Parameters

str — source string expression.
start — 1-based starting position.
len — optional number of characters to extract.

Return Value

A substring of str from start onward, limited to len characters if specified.

Parameters

Name | Description
str | Source string expression.
start | 1-based position of the first character to include.
len (opt) | Maximum number of characters to include.

Examples

#DIM ALL
LOCAL s AS STRING
s = MID$("PowerBASIC", 6)      ' s = "BASIC"
s = MID$("PowerBASIC", 6, 3)   ' s = "BAS"
s = MID$("Hello", 1, 2)        ' s = "He"
s = MID$("Hello", 10)          ' s = "" (empty)

Assembler Output

The compiler calls __pb_mid with the string, start, and optional length:

; PBXA64 x64 assembly for MID$(str, start)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
mov rdx, [rbp-8]         ; pass start in RDX
call __pb_mid            ; returns substring descriptor in RAX
mov [rbp-64], rax        ; store result

; MID$(str, start, len):
mov rcx, [rbp-48]        ; pass descriptor
mov rdx, [rbp-8]         ; pass start
mov r8, [rbp-16]         ; pass len in R8
call __pb_mid
mov [rbp-80], rax

See Also

  • LEFT$
  • RIGHT$
  • INSTR


SPACE$ - PBXA64 Compiler Help

SPACE$

Returns a string consisting of a specified number of space characters.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = SPACE$(n)

Description

SPACE$ creates a new string containing n space characters (ANSI code 32). The runtime helper __pb_space allocates a new PB_STRING64 descriptor with a buffer of n bytes, fills every byte with 0x20 (space), and returns the descriptor. This is a convenience wrapper around STRING$(n, " ") but is slightly more efficient because the fill character is hardcoded.

Parameters

n — LONG integer specifying the number of spaces. Must be non-negative.

Return Value

A string containing n space characters.

Parameters

Name | Description
n | Number of spaces to generate. Zero returns an empty string.

Examples

#DIM ALL
LOCAL s AS STRING
s = SPACE$(5)            ' s = "     " (5 spaces)
s = SPACE$(0)            ' s = "" (empty)
PRINT "[" + SPACE$(3) + "]"  ' prints "[   ]"

Assembler Output

The compiler calls __pb_space with the count in RCX:

; PBXA64 x64 assembly for SPACE$(n)
mov rcx, [rbp-8]         ; pass count in RCX
call __pb_space          ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result

See Also

  • STRING$
  • REPEAT$
  • TAB$


INSTR - PBXA64 Compiler Help

INSTR

Returns the position of one string within another, with an optional starting offset.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

p& = INSTR(str, search)
p& = INSTR(start, str, search)

Description

INSTR searches for the first occurrence of search within str, starting from the given position (default 1). It returns the 1-based position of the first match, or zero if no match is found. The search is case-sensitive and uses a byte-by-byte comparison. The runtime helper __pb_instr performs an O(n*m) scan, advancing through str and comparing each position against search. For performance-critical code, consider caching the search string or using TALLY for counting occurrences.

Parameters

str — the string to search within.
search — the substring to locate.
start — optional 1-based position to begin the search.

Return Value

A LONG containing the 1-based position of search in str, or 0 if not found.

Parameters

Name | Description
str | String expression to search within.
search | Substring expression to locate.
start (opt) | 1-based position to start searching from. Defaults to 1.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL p AS LONG
s = "The quick brown fox"
p = INSTR(s, "quick")        ' p = 5
p = INSTR(s, "fox")          ' p = 17
p = INSTR(10, s, "o")        ' p = 13 (second 'o' after position 10)
p = INSTR(s, "cat")          ' p = 0 (not found)

Assembler Output

The compiler calls __pb_instr with the search parameters:

; PBXA64 x64 assembly for INSTR(str, search)
mov rcx, [rbp-32]        ; pass str descriptor in RCX
mov rdx, [rbp-64]        ; pass search descriptor in RDX
call __pb_instr          ; returns position in RAX
mov [rbp-8], eax         ; store result (LONG)

; INSTR(start, str, search):
mov rcx, [rbp-8]         ; pass start in RCX
mov rdx, [rbp-48]        ; pass str descriptor in RDX
mov r8, [rbp-80]         ; pass search descriptor in R8
call __pb_instr
mov [rbp-16], eax

See Also

  • TALLY
  • VERIFY
  • MID$


STR$ - PBXA64 Compiler Help

STR$

Converts a numeric expression to its string representation.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = STR$(num)

Description

STR$ converts a numeric value (LONG, QUAD, SINGLE, DOUBLE, or any other numeric type) to its decimal string representation. For integer types, the runtime helper __pb_str performs a standard integer-to-string conversion. For floating-point types (SINGLE, DOUBLE), __pb_str_f64 is called instead, which produces a full-precision decimal representation. The resulting string includes a leading space for positive numbers (matching the traditional BASIC behavior where PRINT uses that space in place of a sign character).

Parameters

num — any numeric expression.

Return Value

A string containing the decimal representation of the number.

Parameters

Name | Description
num | Any numeric expression. Type determines which internal conversion routine is invoked.

Examples

#DIM ALL
LOCAL s AS STRING
s = STR$(42)             ' s = " 42"
s = STR$(-12345)         ' s = "-12345"
s = STR$(3.14159)        ' s = " 3.14159"
s = STR$(100)            ' s = " 100"

Assembler Output

For integer arguments, the integer-to-string helper is called. For floating-point, the F64 path is used:

; PBXA64 x64 assembly for STR$(long)
mov rcx, [rbp-8]         ; pass integer value in RCX
call __pb_str            ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result

; PBXA64 x64 assembly for STR$(double)
movsd xmm0, [rbp-8]      ; pass DOUBLE value in XMM0
call __pb_str_f64         ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result

See Also

  • VAL
  • FORMAT$
  • HEX$


CHR$ - PBXA64 Compiler Help

CHR$

Returns a single-character string whose ANSI code is the specified value.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = CHR$(code)
s$ = CHR$(code1, code2, ...)

Description

CHR$ constructs a string from one or more ANSI character codes. With a single argument, it returns a one-character string. With multiple arguments, it concatenates each character into a multi-character string. The runtime helper __pb_chr allocates a new PB_STRING64 descriptor, allocates character buffer memory, and fills it with the specified byte values. This is commonly used for embedding control characters (tab, CRLF, quotes) into strings.

Parameters

code — a LONG expression in the range 0-255. Multiple codes are separated by commas.

Return Value

A string containing the character(s) corresponding to the specified ANSI codes.

Parameters

Name | Description
code(s) | One or more ANSI character codes (0-255). Multiple arguments produce a multi-character string.

Examples

#DIM ALL
LOCAL s AS STRING
s = CHR$(65)               ' s = "A"
s = CHR$(13, 10)           ' s = CRLF (carriage return + line feed)
s = CHR$(34) + "Hi" + CHR$(34)  ' s = '"Hi"'

Assembler Output

The compiler emits a call to the runtime helper:

; PBXA64 x64 assembly for CHR$(code)
mov rcx, [rbp-8]         ; pass code in RCX (first integer arg)
call __pb_chr            ; returns PB_STRING64 descriptor in RAX
mov [rbp-32], rax        ; store result string descriptor

; Multiple arguments are handled by stacking calls:
mov rcx, 13
call __pb_chr            ; get CR
push rax                 ; save on stack
mov rcx, 10
call __pb_chr            ; get LF
mov rdx, rax
pop rcx
call __pb_concat         ; concatenate CR + LF
mov [rbp-32], rax

See Also

  • ASC
  • ASCW
  • STRING$


ASC - PBXA64 Compiler Help

ASC

Returns the ASCII (ANSI) code of the first character in a string, or the character at a specified position.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

c& = ASC(str)
c& = ASC(str, index)

Description

ASC returns the 8-bit ANSI code (0-255) of the character at the given position. If no index is specified, the first character (position 1) is used. If the index is out of range (less than 1 or greater than LEN(str)), the result is undefined. PB_STRING64 stores the character data as a byte array; ASC performs a direct byte load from the data pointer plus the index offset.

Parameters

str — string expression to evaluate.
index — optional LONG (1-based) position of the desired character.

Return Value

A LONG containing the ANSI code (0-255) of the specified character.

Parameters

Name | Description
str | String expression from which to extract a character code.
index (opt) | 1-based character position. Defaults to 1 if omitted.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL c AS LONG
s = "PowerBASIC"
c = ASC(s)          ' c = 80 ('P')
c = ASC(s, 6)       ' c = 66 ('B')
c = ASC("ABC")      ' c = 65 ('A')

Assembler Output

The compiler loads the data pointer and indexes into the byte buffer:

; PBXA64 x64 assembly for ASC(str)
mov rax, [rbp-32]        ; load PB_STRING64 descriptor
mov rax, [rax]           ; read data_ptr
movzx eax, byte [rax]    ; load first byte, zero-extend
mov [rbp-8], eax         ; store result

; ASC(str, index):
mov rax, [rbp-32]        ; load descriptor
mov rax, [rax]           ; read data_ptr
mov rcx, [rbp-8]         ; load index (1-based)
dec rcx                  ; convert to 0-based
movzx eax, byte [rax+rcx] ; load byte at offset
mov [rbp-16], eax        ; store result

See Also

  • CHR$
  • ASCW
  • LEN


STRING$ - PBXA64 Compiler Help

STRING$

Returns a string consisting of a specified number of copies of a character.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = STRING$(count, char)
s$ = STRING$(count, code)

Description

STRING$ creates a new string containing count copies of a single character. The character can be specified either as a single-character string (char) or as an ANSI code (code, 0-255). The runtime helper __pb_string allocates a new PB_STRING64 descriptor, allocates a count-byte buffer, and fills it with the specified byte value using memset or a simple REP STOSB loop. This is more flexible than SPACE$ for generating repeated non-space characters.

Parameters

count — number of repetitions (LONG, non-negative).
char — single-character string to repeat.
code — ANSI byte code (0-255) to repeat.

Return Value

A string containing count copies of the specified character.

Parameters

Name | Description
count | Number of times to repeat the character. Zero returns empty string.
char / code | The character to repeat. Either as a 1-character string or a byte code 0-255.

Examples

#DIM ALL
LOCAL s AS STRING
s = STRING$(10, "*")     ' s = "**********"
s = STRING$(5, 65)       ' s = "AAAAA" (65 = 'A')
s = STRING$(3, "X")      ' s = "XXX"

Assembler Output

The compiler calls __pb_string with count and character:

; PBXA64 x64 assembly for STRING$(count, char$)
mov rcx, [rbp-8]         ; pass count in RCX
mov rdx, [rbp-32]        ; pass char descriptor in RDX
call __pb_string         ; returns PB_STRING64 descriptor in RAX
mov [rbp-64], rax        ; store result

; STRING$(count, code):
mov rcx, [rbp-8]         ; pass count
mov rdx, [rbp-16]        ; pass code as byte value
call __pb_string
mov [rbp-48], rax

See Also

  • SPACE$
  • REPEAT$
  • CHR$


FORMAT$ - PBXA64 Compiler Help

FORMAT$

Formats a numeric value according to a picture-string template.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = FORMAT$(num, format$)

Description

FORMAT$ converts a numeric value to a formatted string using a picture template string. The format string can contain placeholder characters: '#' for optional digits, '0' for forced digits, '.' for decimal point, ',' for thousands separator, '%' for percentage scaling, '$' for dollar sign, and '-' for negative sign placement. The runtime helper __pb_format parses the picture string and formats the number accordingly. This is more flexible than STR$ for producing human-readable output like currency values or aligned columns.

Parameters

num — numeric expression to format.
format$ — picture template string describing the output format.

Return Value

A string containing the formatted number.

Parameters

Name | Description
num | Numeric expression to format.
format$ | Picture format string using #, 0, ., , %, and other specifiers.

Examples

#DIM ALL
LOCAL s AS STRING
s = FORMAT$(1234.5, "##,##0.00")   ' s = "1,234.50"
s = FORMAT$(0.5, "0.00%")          ' s = "50.00%"
s = FORMAT$(-42, "(#)")            ' s = "(42)"
s = FORMAT$(255, "0000")           ' s = "0255"

Assembler Output

The compiler calls __pb_format with the value and picture string:

; PBXA64 x64 assembly for FORMAT$(num, format$)
mov rcx, [rbp-8]         ; pass numeric value (DOUBLE) in XMM0
movsd xmm0, rcx
mov rdx, [rbp-48]        ; pass format$ descriptor in RDX
call __pb_format         ; returns PB_STRING64 descriptor in RAX
mov [rbp-80], rax        ; store result

See Also

  • STR$
  • VAL
  • HEX$


VAL - PBXA64 Compiler Help

VAL

Converts a string expression to a numeric value (DOUBLE precision).

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

n# = VAL(str)

Description

VAL parses a string containing a numeric literal and returns its DOUBLE value. Parsing stops at the first character that cannot be part of a number (including the null terminator). The function handles leading whitespace, an optional sign, decimal digits, an optional decimal point, and an optional exponent (E or D). If the string does not start with a valid numeric character, VAL returns zero. For explicit integer parsing without floating-point overhead, use VALI or CVL.

Parameters

str — string expression containing a numeric representation.

Return Value

A DOUBLE-precision floating-point value parsed from the string.

Parameters

Name | Description
str | String expression containing text that represents a number.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL v AS DOUBLE
v = VAL("3.14159")       ' v = 3.14159
v = VAL("  -42")         ' v = -42
v = VAL("1.5e10")        ' v = 15000000000
v = VAL("ABC")           ' v = 0 (invalid)

Assembler Output

The compiler calls the generic string-to-double runtime helper:

; PBXA64 x64 assembly for VAL(str)
mov rcx, [rbp-32]        ; pass PB_STRING64 descriptor in RCX
call __pb_val            ; returns DOUBLE in XMM0
movsd [rbp-8], xmm0      ; store result

See Also

  • STR$
  • VALI
  • VALD


DIR$ - PBXA64 Compiler Help

DIR$

Returns the name of a file matching a filespec pattern, or iterates through multiple matches.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = DIR$
s$ = DIR$(pattern)
s$ = DIR$(pattern, attrs)

Description

DIR$ returns the name of the first file matching the specified pattern and attributes. Subsequent calls with no arguments return additional matching filenames until no more matches exist, at which point an empty string is returned. The attrs parameter controls which file types are included (e.g., normal, hidden, system, directory, volume). The runtime helper __pb_dir wraps the Windows FindFirstFile/FindNextFile API. Calling DIR$ with a new pattern resets the internal search handle.

Parameters

pattern — filespec with optional wildcards (* and ?).
attrs — optional attribute flags (combination of %NORMAL, %HIDDEN, %SYSTEM, %DIRECTORY, etc.).

Return Value

A string containing a filename, or an empty string when no more matches exist.

Parameters

Name | Description
pattern (opt) | File pattern (e.g., "*.txt", "data.*"). Wildcards supported.
attrs (opt) | File attribute filter. Defaults to normal files.

Examples

#DIM ALL
LOCAL s AS STRING
s = DIR$("*.exe")         ' first .exe file
DO WHILE LEN(s)
    PRINT s
    s = DIR$()            ' next .exe file
LOOP

Assembler Output

The compiler calls __pb_dir with the pattern and attributes:

; PBXA64 x64 assembly for DIR$(pattern)
mov rcx, [rbp-32]        ; pass pattern descriptor in RCX
call __pb_dir            ; returns filename descriptor in RAX
mov [rbp-64], rax        ; store result

; DIR$() -- no args:
call __pb_dir_next       ; returns next filename in RAX
mov [rbp-64], rax

See Also

  • CURDIR$
  • GETATTR
  • KILL


COMMAND$ - PBXA64 Compiler Help

COMMAND$

Returns the command-line arguments passed to the program.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = COMMAND$
s$ = COMMAND$(n)

Description

COMMAND$ returns the command-line string that was used to invoke the program. Without an argument, the entire command line (excluding the program name) is returned. With an integer argument n, it returns the nth individual token (delimited by spaces or tabs) from the command line. If n exceeds the number of tokens, an empty string is returned. The runtime helper __pb_command parses the command line stored by the C runtime startup code (retrieved via GetCommandLineA or __argv).

Parameters

n — optional token index (1-based) for retrieving a specific argument.

Return Value

A string containing the command line or a specific token.

Parameters

Name | Description
n (opt) | 1-based index of the argument token to retrieve.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL i AS LONG
s = COMMAND$             ' entire command line
FOR i = 1 TO PARSECOUNT
    PRINT COMMAND$(i)    ' print each argument
NEXT

Assembler Output

The compiler calls __pb_command to retrieve arguments:

; PBXA64 x64 assembly for COMMAND$
call __pb_command        ; returns full command line in RAX
mov [rbp-32], rax        ; store result

; COMMAND$(n):
mov rcx, [rbp-8]         ; pass token index in RCX
call __pb_command        ; returns nth token in RAX
mov [rbp-48], rax

See Also

  • ENVIRON$
  • CURDIR$
  • DIR$


ENVIRON$ - PBXA64 Compiler Help

ENVIRON$

Returns the value of an operating system environment variable.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = ENVIRON$(name)
s$ = ENVIRON$(n)

Description

ENVIRON$ retrieves the value of an environment variable. When passed a string name (e.g., "PATH", "TEMP"), the function returns the variable's value, or an empty string if it does not exist. When passed a positive integer n, it returns the nth entry from the environment block in "NAME=VALUE" format. The runtime helper __pb_environ wraps the Windows GetEnvironmentVariableA API for named lookups and iterates the process environment block for index-based lookups.

Parameters

name — string containing the environment variable name.
n — 1-based index into the environment block.

Return Value

A string containing the environment variable value, or empty if not found.

Parameters

Name | Description
name | Environment variable name (case-insensitive on Windows).
n | 1-based index into the environment block enumeration.

Examples

#DIM ALL
LOCAL s AS STRING
s = ENVIRON$("PATH")     ' returns the system PATH
s = ENVIRON$("TEMP")     ' returns temp directory path
s = ENVIRON$(1)          ' first environment entry

Assembler Output

The compiler calls __pb_environ with either a name string or index:

; PBXA64 x64 assembly for ENVIRON$(name$)
mov rcx, [rbp-32]        ; pass name descriptor in RCX
call __pb_environ        ; returns value descriptor in RAX
mov [rbp-64], rax        ; store result

; ENVIRON$(n):
mov rcx, [rbp-8]         ; pass integer index in RCX
call __pb_environ_index  ; returns entry descriptor in RAX
mov [rbp-48], rax

See Also

  • COMMAND$
  • CURDIR$
  • DIR$


CURDIR$ - PBXA64 Compiler Help

CURDIR$

Returns the current working directory as a string.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = CURDIR$

Description

CURDIR$ returns the absolute path of the current working directory. The runtime helper __pb_curdir calls GetCurrentDirectoryA from the Windows API, retrieves the full path, and wraps it in a PB_STRING64 descriptor. The path does not include a trailing backslash except for the root directory (e.g., "C:\"). This is useful for file operations that need to resolve relative paths or display the current location to the user.

Parameters

None.

Return Value

A string containing the absolute path of the current directory.

Parameters

Name | Description
(none) | No parameters required.

Examples

#DIM ALL
LOCAL s AS STRING
s = CURDIR$
PRINT "Current directory: " + s

Assembler Output

The compiler calls __pb_curdir with no arguments:

; PBXA64 x64 assembly for CURDIR$
call __pb_curdir         ; returns path descriptor in RAX
mov [rbp-32], rax        ; store result

See Also

  • DIR$
  • CHDIR
  • COMMAND$


ASCW - PBXA64 Compiler Help

ASCW

Returns the Unicode (UTF-16) code of the first wide character in a WSTRING (or ANSI string).

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

c& = ASCW(str)
c& = ASCW(str, index)

Description

ASCW returns the UTF-16 code unit (0-65535) of the wide character at the given position. For ANSI strings, the character is first converted to its Unicode equivalent via the current ANSI code page. For WSTRING variables, the wide character is read directly from the character buffer. With no index, the first character is used. If the string is empty or the index is out of range, ASCW returns zero.

Parameters

str — string expression (ANSI or WSTRING).
index — optional 1-based character position.

Return Value

A LONG containing the Unicode code point (0-65535) of the specified character.

Parameters

Name | Description
str | String expression (STRING or WSTRING) to evaluate.
index (opt) | 1-based position of the character. Defaults to 1.

Examples

#DIM ALL
LOCAL s AS STRING
LOCAL c AS LONG
s = "ABC"
c = ASCW(s)              ' c = 65 ('A')
c = ASCW(s, 2)           ' c = 66 ('B')

Assembler Output

For WSTRING variables, the compiler reads a WORD from the buffer:

; PBXA64 x64 assembly for ASCW(str) -- WSTRING
mov rax, [rbp-32]        ; load WSTRING descriptor
mov rax, [rax]           ; read data_ptr
movzx eax, word [rax]    ; load first wide char, zero-extend
mov [rbp-8], eax         ; store result

; For ANSI strings, a conversion stub is called:
mov rcx, [rbp-32]        ; pass ANSI string descriptor
call __pb_ascw_from_ansi ; returns Unicode code in RAX
mov [rbp-8], eax

See Also

  • ASC
  • CHR$
  • LEN


PARSECOUNT - PBXA64 Compiler Help

PARSECOUNT

Returns the number of delimited fields in a string.

Kind: Function | Category: String

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

count& = PARSECOUNT(str[, delimiter$])

Description

PARSECOUNT returns the number of substring fields in str delimited by delimiter (default is any whitespace). Scanning is performed via strstr — each occurrence of the delimiter increments the field count. The function always returns at least 1 (the entire string is one field if no delimiter is found).

Examples

LOCAL c AS LONG
c = PARSECOUNT("a,b,c", ",")    ' c = 3
c = PARSECOUNT("hello world")   ' c = 2

Assembler Output

; PARSECOUNT inline strstr loop
; char* p = str; LONG count = 1
; while (p = strstr(p, delim)) { count++; p += delimLen; }
loop_top:
 call strstr
 test rax, rax
 je done
 inc count
 add rax, delim_len
 jmp loop_top
done:

See Also

  • PARSE$
  • SPLIT
  • Back to command index


MATCH - PBXA64 Compiler Help

MATCH

Pattern matching with wildcards (? and *).

Kind: Function | Category: String

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

match& = expr LIKE pattern

Description

MATCH performs pattern matching using the LIKE operator. The wildcard ? matches any single character; * matches zero or more characters. Uses the Win32 API PathMatchSpecA from shlwapi.dll for pattern matching. Returns non-zero (TRUE) if the expression matches the pattern, or zero (FALSE) otherwise.

Examples

IF "hello.txt" LIKE "*.txt" THEN PRINT "Match!"

Assembler Output

; MATCH calls PathMatchSpecA
 lea rcx, [expr_str]
 lea rdx, [pattern_str]
 call PathMatchSpecA
 test eax, eax
 setnz al

See Also

  • INSTR
  • SCAN
  • Back to command index


LSET - PBXA64 Compiler Help

LSET

Left-aligns a source string into a destination string variable, padding with spaces on the right.

Kind: Statement | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LSET dest = source

Description

LSET copies the source string into the destination string variable, left-aligning it within the destination's current capacity. If source is shorter than dest, the remaining space is filled with spaces (ANSI 32) on the right. If source is longer, it is truncated to fit dest's length. The destination's length field is set to the destination's original length (not the source length), so padding is maintained. LSET does not reallocate the destination buffer. The runtime helper __pb_str_lset performs an in-place copy with padding.

Parameters

dest — string variable to receive the aligned result.
source — string expression to left-align into dest.

Return Value

None. The destination string is modified in place.

Parameters

Name | Description
dest | String variable (left side of =). Must be a variable, not a literal.
source | String expression to copy into dest.

Examples

#DIM ALL
LOCAL a AS STRING * 10
LOCAL b AS STRING
a = "Hello"
LSET a = "Hi"        ' a = "Hi        " (10 chars, right-padded)
LSET a = "LongerTextHere"  ' a = "LongerText" (truncated to 10)

Assembler Output

The compiler calls __pb_str_lset with both descriptors:

; PBXA64 x64 assembly for LSET dest = source
mov rcx, [rbp-32]        ; pass dest descriptor in RCX
mov rdx, [rbp-64]        ; pass source descriptor in RDX
call __pb_str_lset       ; modifies dest in place

See Also

  • RSET
  • MID$ (statement form)
  • TRIM$


RSET - PBXA64 Compiler Help

RSET

Right-aligns a source string into a destination string variable, padding with spaces on the left.

Kind: Statement | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

RSET dest = source

Description

RSET copies the source string into the destination string variable, right-aligning it within the destination's current capacity. If source is shorter than dest, the remaining space is filled with spaces on the left. If source is longer, it is truncated from the left (the rightmost characters are kept). The runtime helper __pb_str_rset calculates the offset where source should be placed (dest_len - source_len), fills the left portion with spaces, and copies source to the rightmost portion. The destination's length field is not changed.

Parameters

dest — string variable to receive the aligned result.
source — string expression to right-align into dest.

Return Value

None. The destination string is modified in place.

Parameters

Name | Description
dest | String variable (left side of =). Must be a variable, not a literal.
source | String expression to copy into dest, right-aligned.

Examples

#DIM ALL
LOCAL a AS STRING * 10
a = "Hello"
RSET a = "Hi"        ' a = "        Hi" (10 chars, left-padded)
RSET a = "LongText"  ' a = "  LongText"

Assembler Output

The compiler calls __pb_str_rset with both descriptors:

; PBXA64 x64 assembly for RSET dest = source
mov rcx, [rbp-32]        ; pass dest descriptor in RCX
mov rdx, [rbp-64]        ; pass source descriptor in RDX
call __pb_str_rset       ; modifies dest in place

See Also

  • LSET
  • MID$ (statement form)
  • TRIM$


SPLIT - PBXA64 Compiler Help

SPLIT

Splits a string into an array of substrings based on a delimiter.

Kind: Statement | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SPLIT source BY delimiter TO array

Description

SPLIT parses source string into substrings delimited by delimiter and stores each substring as an element in array. The array is automatically REDIMed to the required size. If delimiter is empty, the string is split into individual characters. The runtime helper builds the result by scanning source for occurrences of delimiter, creating a PB_STRING64 descriptor for each segment, and storing them in the target string array. After SPLIT, the array LBOUND is 1 and UBOUND equals the number of fragments.

Parameters

source — string expression to split.
delimiter — string expression that separates the substrings.
array — string array variable that receives the fragments.

Return Value

None. The array is populated with the split fragments.

Parameters

Name | Description
source | String expression to be split into parts.
delimiter | String marking the boundary between fragments.
array | String array variable receiving the resulting fragments.

Examples

#DIM ALL
LOCAL s() AS STRING
SPLIT "a,b,c,d" BY "," TO s()
' s(1) = "a", s(2) = "b", s(3) = "c", s(4) = "d"

SPLIT "Hello World" BY " " TO s()
' s(1) = "Hello", s(2) = "World"

Assembler Output

The SPLIT statement inlines a scanning loop or calls the runtime helper:

; PBXA64 x64 assembly for SPLIT source BY delimiter TO array()
mov rcx, [rbp-32]        ; pass source descriptor in RCX
mov rdx, [rbp-64]        ; pass delimiter descriptor in RDX
mov r8, [rbp-80]         ; pass array descriptor pointer in R8
call __pb_split          ; populates array with fragments

See Also

  • JOIN$
  • INSTR
  • TALLY


JOIN$ - PBXA64 Compiler Help

JOIN$

Joins the elements of a string array into a single string with a delimiter between each element.

Kind: Function | Category: String Functions

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = JOIN$(array, delimiter)

Description

JOIN$ concatenates all elements of a string array into a single string, inserting delimiter between each element. No delimiter is appended after the last element. The runtime helper __pb_join iterates through the array (from LBOUND to UBOUND), calculates the total buffer length (sum of element lengths + delimiter lengths for n-1 gaps), allocates a new PB_STRING64 descriptor, and copies each element with interleaved delimiters. This is the inverse operation of SPLIT.

Parameters

array — string array whose elements will be concatenated.
delimiter — string to insert between array elements.

Return Value

A string containing all array elements joined by the delimiter.

Parameters

Name | Description
array | String array (one-dimensional) containing elements to join.
delimiter | String separator placed between elements.

Examples

#DIM ALL
LOCAL s() AS STRING
LOCAL result AS STRING
REDIM s(1 TO 3)
s(1) = "apple"
s(2) = "banana"
s(3) = "cherry"
result = JOIN$(s(), ", ")        ' result = "apple, banana, cherry"
result = JOIN$(s(), "")          ' result = "applebananacherry"

Assembler Output

The compiler calls __pb_join with the array and delimiter:

; PBXA64 x64 assembly for JOIN$(array(), delimiter)
mov rcx, [rbp-64]        ; pass array descriptor pointer in RCX
mov rdx, [rbp-96]        ; pass delimiter descriptor in RDX
call __pb_join           ; returns joined string descriptor in RAX
mov [rbp-128], rax       ; store result

See Also

  • SPLIT
  • REPEAT$
  • REPLACE$


ABS - PBXA64 Compiler Help

ABS

Returns the absolute value of a numeric expression.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = ABS(num)

Description

ABS returns the absolute (unsigned) magnitude of num. For positive numbers and zero, the result equals the input. For negative numbers, the sign bit is cleared, yielding the positive magnitude. ABS accepts INTEGER, LONG, QUAD, SINGLE, and DOUBLE operands; the return type matches the input type.

Parameters

Parameter | Description
num | Numeric expression. Must evaluate to a numeric type (INTEGER, LONG, QUAD, SINGLE, or DOUBLE).

Examples

n = ABS(-5)       ' n = 5
d = ABS(-3.14)    ' d = 3.14
PRINT ABS(0)      ' prints 0

Assembler Output

The compiler generates the following x64 code for this command:

; For signed integer types:
mov  rax, rcx      ; copy value
neg  rax           ; negate
cmovl rax, rcx     ; if result was negative (overflow), keep original (positive)

; For DOUBLE via XMM0:
movq  rax, xmm0    ; copy raw bits
btc   rax, 63      ; clear sign bit (bit 63)
movq  xmm0, rax    ; store back

See Also

  • SGN
  • INT


SGN - PBXA64 Compiler Help

SGN

Returns the sign of a numeric expression as -1, 0, or 1.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = SGN(num)

Description

SGN evaluates num and returns -1 if the value is negative, 0 if the value is zero, or 1 if the value is positive. The result is always a signed LONG integer regardless of the input type.

Parameters

Parameter | Description
num | Numeric expression of any type.

Examples

PRINT SGN(-42)    ' prints -1
PRINT SGN(0)      ' prints 0
PRINT SGN(3.14)   ' prints 1

Assembler Output

The compiler generates the following x64 code for this command:

; SGN for signed integer in RCX:
cmp  rcx, 0
jl   negative
jg   positive
xor  eax, eax
ret
negative:
mov  rax, -1
ret
positive:
mov  rax, 1
ret

; For DOUBLE in XMM0:
movq  rax, xmm0
test  rax, rax
jl    negative_d
cmp   rax, 0
je    zero_d
mov   eax, 1
ret
zero_d:
xor   eax, eax
ret
negative_d:
mov   eax, -1
ret

See Also

  • ABS
  • INT


INT - PBXA64 Compiler Help

INT

Returns the floor (largest integer less than or equal to the value).

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = INT(num)

Description

INT returns the floor of num — the largest whole number that is less than or equal to num. Unlike FIX, which truncates toward zero, INT rounds downward for negative numbers. For example, INT(-3.7) returns -4 while FIX(-3.7) returns -3. The result is a signed LONG or QUAD integer.

Parameters

Parameter | Description
num | Numeric expression. Typically DOUBLE or SINGLE; INTEGER types are returned unchanged.

Examples

PRINT INT(3.14)    ' prints 3
PRINT INT(-3.14)   ' prints -4
PRINT INT(-3.0)    ' prints -3
x = INT(99.999)    ' x = 99

Assembler Output

The compiler generates the following x64 code for this command:

; INT for DOUBLE in XMM0:
cvttsd2si rax, xmm0   ; truncate toward zero → rax (signed)
cvtsi2sd  xmm1, rax   ; convert back to double
ucomisd   xmm0, xmm1  ; compare original with truncated
je        done         ; equal → no adjustment
jae       done         ; original >= truncated → no adjustment
dec       rax          ; original < truncated → subtract 1 (floor)
done:
ret

See Also

  • FIX
  • ROUND
  • FRAC


FIX - PBXA64 Compiler Help

FIX

Truncates a numeric value toward zero, removing the fractional part.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = FIX(num)

Description

FIX removes the fractional part of num, truncating toward zero. Unlike INT, which floors toward negative infinity, FIX simply discards the fractional digits. For positive numbers FIX and INT behave identically; for negative numbers FIX returns the next integer toward zero (e.g. FIX(-3.7) = -3, INT(-3.7) = -4). The result is a signed LONG or QUAD integer.

Parameters

Parameter | Description
num | Numeric expression. Typically DOUBLE or SINGLE; INTEGER types are returned unchanged.

Examples

PRINT FIX(3.99)    ' prints 3
PRINT FIX(-3.99)   ' prints -3
PRINT FIX(0.5)     ' prints 0

Assembler Output

The compiler generates the following x64 code for this command:

; FIX for DOUBLE in XMM0:
cvttsd2si rax, xmm0   ; truncate toward zero (truncation is implicit)
ret

See Also

  • INT
  • ROUND


FRAC - PBXA64 Compiler Help

FRAC

Returns the fractional part of a numeric value.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = FRAC(num)

Description

FRAC returns the fractional portion of num, computed as num - FIX(num). The result has the same sign as the input and is always a DOUBLE. For integer values the result is 0.0.

Parameters

Parameter | Description
num | Numeric expression. Typically DOUBLE or SINGLE.

Examples

PRINT FRAC(3.14)    ' prints 0.14
PRINT FRAC(-2.5)    ' prints -0.5
PRINT FRAC(7.0)     ' prints 0.0

Assembler Output

The compiler generates the following x64 code for this command:

; FRAC for DOUBLE in XMM0:
cvttsd2si rax, xmm0   ; truncate toward zero
cvtsi2sd  xmm1, rax   ; convert back to double
subsd     xmm0, xmm1  ; subtract integer part → fractional part
ret

See Also

  • INT
  • FIX


MIN - PBXA64 Compiler Help

MIN

Returns the smaller of two numeric values.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = MIN(a, b)

Description

MIN compares two numeric values and returns the smaller (minimum) of the two. For integer types the comparison uses signed arithmetic. For floating-point types NaN is treated as greater than all other values.

Parameters

Parameter | Description
a | First numeric expression.
b | Second numeric expression.

Examples

PRINT MIN(5, 10)    ' prints 5
PRINT MIN(-3, -1)   ' prints -3
x = MIN(3.14, 2.71) ' x = 2.71

Assembler Output

The compiler generates the following x64 code for this command:

; MIN for signed integers:
cmp  rcx, rdx     ; compare a vs b
cmovl rax, rcx    ; if a < b, result = a
cmovge rax, rdx   ; if a >= b, result = b

; MIN for DOUBLE:
comisd xmm0, xmm1 ; compare a vs b
movsd  xmm2, xmm1
minsd  xmm0, xmm1 ; SSE2 minsd — result = min(a, b)

See Also

  • MAX
  • CLAMP


MAX - PBXA64 Compiler Help

MAX

Returns the larger of two numeric values.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = MAX(a, b)

Description

MAX compares two numeric values and returns the larger (maximum) of the two. For integer types the comparison uses signed arithmetic. For floating-point types NaN is treated as greater than all other values.

Parameters

Parameter | Description
a | First numeric expression.
b | Second numeric expression.

Examples

PRINT MAX(5, 10)    ' prints 10
PRINT MAX(-3, -1)   ' prints -1
x = MAX(3.14, 2.71) ' x = 3.14

Assembler Output

The compiler generates the following x64 code for this command:

; MAX for signed integers:
cmp  rcx, rdx     ; compare a vs b
cmovg rax, rcx    ; if a > b, result = a
cmovle rax, rdx   ; if a <= b, result = b

; MAX for DOUBLE:
comisd xmm0, xmm1 ; compare a vs b
maxsd  xmm0, xmm1 ; SSE2 maxsd — result = max(a, b)

See Also

  • MIN
  • CLAMP


CLAMP - PBXA64 Compiler Help

CLAMP

Constrains a numeric value to a specified range.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = CLAMP(val, lo, hi)

Description

CLAMP restricts val to the inclusive range [lo, hi]. If val < lo, the result is lo. If val > hi, the result is hi. Otherwise the result is val unchanged. It is equivalent to MAX(lo, MIN(hi, val)).

Parameters

Parameter | Description
val | Numeric expression to constrain.
lo | Lower bound (inclusive).
hi | Upper bound (inclusive). Must be ≥ lo.

Examples

PRINT CLAMP(5, 0, 10)   ' prints 5
PRINT CLAMP(-5, 0, 10)  ' prints 0
PRINT CLAMP(20, 0, 10)  ' prints 10
x = CLAMP(v, 1, 100)    ' keep v in range [1,100]

Assembler Output

The compiler generates the following x64 code for this command:

; CLAMP for signed integers (val=R8, lo=RDX, hi=R8):
; Chain of conditional moves:
cmp  r8, rdx       ; compare val vs lo
cmovl r8, rdx      ; if val < lo, val = lo
cmp  r8, r9        ; compare val vs hi
cmovg r8, r9       ; if val > hi, val = hi
mov  rax, r8       ; result in RAX

; CLAMP for DOUBLE:
minsd  xmm0, xmm2  ; val = min(val, hi)
maxsd  xmm0, xmm1  ; val = max(val, lo)
; result in XMM0

See Also

  • MIN
  • MAX


SIN - PBXA64 Compiler Help

SIN

Returns the trigonometric sine of an angle measured in radians.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = SIN(radians)

Description

SIN computes the sine of the angle given in radians. The result is a DOUBLE in the range [-1.0, 1.0]. To convert degrees to radians, multiply by (PI / 180).

Parameters

Parameter | Description
radians | Angle in radians (DOUBLE or SINGLE).

Examples

PRINT SIN(0.0)      ' prints 0.0
PRINT SIN(3.14159)  ' prints approx 0.0 (PI radians = 180 degrees)
d = 90 * (3.14159/180)
PRINT SIN(d)        ' prints approx 1.0

Assembler Output

The compiler generates the following x64 code for this command:

SIN delegates to the C runtime library:

; SIN for DOUBLE in XMM0:
sub  rsp, 40
call __imp_sin    ; msvcrt sin() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • COS
  • TAN
  • ATN


COS - PBXA64 Compiler Help

COS

Returns the trigonometric cosine of an angle measured in radians.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = COS(radians)

Description

COS computes the cosine of the angle given in radians. The result is a DOUBLE in the range [-1.0, 1.0]. To convert degrees to radians, multiply by (PI / 180).

Parameters

Parameter | Description
radians | Angle in radians (DOUBLE or SINGLE).

Examples

PRINT COS(0.0)      ' prints 1.0
PRINT COS(3.14159)  ' prints approx -1.0
d = 60 * (3.14159/180)
PRINT COS(d)        ' prints approx 0.5

Assembler Output

The compiler generates the following x64 code for this command:

; COS for DOUBLE in XMM0:
sub  rsp, 40
call __imp_cos    ; msvcrt cos() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • SIN
  • TAN


TAN - PBXA64 Compiler Help

TAN

Returns the trigonometric tangent of an angle measured in radians.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = TAN(radians)

Description

TAN computes the tangent of the angle given in radians, defined as SIN(radians) / COS(radians). The result is a DOUBLE. For angles where COS approaches zero, the result may be extremely large or infinity.

Parameters

Parameter | Description
radians | Angle in radians (DOUBLE or SINGLE).

Examples

PRINT TAN(0.0)      ' prints 0.0
PRINT TAN(45 * 3.14159/180)  ' prints approx 1.0

Assembler Output

The compiler generates the following x64 code for this command:

; TAN for DOUBLE in XMM0:
sub  rsp, 40
call __imp_tan    ; msvcrt tan() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • SIN
  • COS
  • ATN


ATN - PBXA64 Compiler Help

ATN

Returns the principal arctangent (inverse tangent) of a numeric value.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = ATN(num)

Description

ATN computes the arctangent of num, returning an angle in radians in the range [-PI/2, PI/2]. The result is a DOUBLE. ATN is the inverse of TAN.

Parameters

Parameter | Description
num | Numeric expression (DOUBLE or SINGLE).

Examples

PRINT ATN(0.0)      ' prints 0.0
PRINT ATN(1.0)      ' prints approx 0.785398 (PI/4)
PRINT ATN(1000)     ' prints approx 1.5698 (near PI/2)

Assembler Output

The compiler generates the following x64 code for this command:

; ATN for DOUBLE in XMM0:
sub  rsp, 40
call __imp_atan   ; msvcrt atan() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • SIN
  • COS
  • TAN


EXP - PBXA64 Compiler Help

EXP

Returns the base-e exponential of a numeric value (e^x).

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = EXP(x)

Description

EXP computes e raised to the power of x, where e is Euler's constant (approximately 2.71828). The result is a DOUBLE. For large values of x the result may overflow to infinity.

Parameters

Parameter | Description
x | Numeric exponent (DOUBLE or SINGLE).

Examples

PRINT EXP(0.0)    ' prints 1.0
PRINT EXP(1.0)    ' prints approx 2.71828
PRINT EXP(-1.0)   ' prints approx 0.36788

Assembler Output

The compiler generates the following x64 code for this command:

; EXP for DOUBLE in XMM0:
sub  rsp, 40
call __imp_exp    ; msvcrt exp() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • LOG
  • LOG2
  • LOG10


LOG - PBXA64 Compiler Help

LOG

Returns the natural logarithm (base e) of a numeric value.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = LOG(x)

Description

LOG computes the natural logarithm of x. The argument must be positive (x > 0). If x is zero or negative, the result is undefined and may produce -inf or NaN.

Parameters

Parameter | Description
x | Positive numeric expression (DOUBLE or SINGLE).

Examples

PRINT LOG(1.0)    ' prints 0.0
PRINT LOG(2.71828) ' prints approx 1.0
PRINT LOG(100)    ' prints approx 4.60517

Assembler Output

The compiler generates the following x64 code for this command:

; LOG for DOUBLE in XMM0:
sub  rsp, 40
call __imp_log    ; msvcrt log() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • EXP
  • LOG2
  • LOG10


SQR - PBXA64 Compiler Help

SQR

Returns the square root of a numeric value.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = SQR(x)

Description

SQR returns the non-negative square root of x. The argument must be non-negative (x ≥ 0). For negative arguments the result is NaN.

Parameters

Parameter | Description
x | Non-negative numeric expression (DOUBLE or SINGLE).

Examples

PRINT SQR(0.0)    ' prints 0.0
PRINT SQR(9.0)    ' prints 3.0
PRINT SQR(2.0)    ' prints approx 1.41421

Assembler Output

The compiler generates the following x64 code for this command:

; SQR for DOUBLE in XMM0:
sub  rsp, 40
call __imp_sqrt   ; msvcrt sqrt() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • POW
  • EXP


LOG2 - PBXA64 Compiler Help

LOG2

Returns the base-2 logarithm of a numeric value.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = LOG2(x)

Description

LOG2 computes the base-2 logarithm of x. It is implemented as LOG(x) / LOG(2). The argument must be positive (x > 0).

Parameters

Parameter | Description
x | Positive numeric expression (DOUBLE or SINGLE).

Examples

PRINT LOG2(1.0)   ' prints 0.0
PRINT LOG2(2.0)   ' prints 1.0
PRINT LOG2(8.0)   ' prints 3.0
PRINT LOG2(256)   ' prints 8.0

Assembler Output

The compiler generates the following x64 code for this command:

; LOG2 for DOUBLE in XMM0:
sub  rsp, 40
call __imp_log     ; natural log
movsd xmm1, [log2_const]   ; log(2) precomputed constant
divsd xmm0, xmm1   ; log2(x) = log(x) / log(2)
add  rsp, 40
ret

; log2_const: .quad 0x3FE62E42FEFA39EF  (ln(2) = 0.6931471805599453)

See Also

  • LOG
  • LOG10
  • EXP


LOG10 - PBXA64 Compiler Help

LOG10

Returns the base-10 logarithm (common logarithm) of a numeric value.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = LOG10(x)

Description

LOG10 computes the base-10 logarithm of x. The argument must be positive (x > 0).

Parameters

Parameter | Description
x | Positive numeric expression (DOUBLE or SINGLE).

Examples

PRINT LOG10(1.0)   ' prints 0.0
PRINT LOG10(10.0)  ' prints 1.0
PRINT LOG10(1000)  ' prints 3.0

Assembler Output

The compiler generates the following x64 code for this command:

; LOG10 for DOUBLE in XMM0:
sub  rsp, 40
call __imp_log10   ; msvcrt log10() — XMM0 = argument, XMM0 = result
add  rsp, 40
ret

See Also

  • LOG
  • LOG2


ROUND - PBXA64 Compiler Help

ROUND

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

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = ROUND(num, places)

Description

ROUND rounds num to the number of decimal places specified by places. If places is 0, the result is rounded to the nearest integer. If places is negative, rounding occurs to the left of the decimal point (e.g. ROUND(1234, -2) = 1200). Standard rounding (half up) is used.

Parameters

Parameter | Description
num | Numeric expression to round (DOUBLE or SINGLE).
places | Integer expression specifying the number of decimal places.

Examples

PRINT ROUND(3.14159, 2)  ' prints 3.14
PRINT ROUND(2.71828, 1)  ' prints 2.7
PRINT ROUND(1234, -2)    ' prints 1200
n = ROUND(3.5, 0)        ' n = 4

Assembler Output

The compiler generates the following x64 code for this command:

; ROUND calls the runtime helper __pb_round:
sub  rsp, 40
mov  rcx, places
call __pb_round   ; uses XMM0 for num, returns rounded in XMM0
add  rsp, 40
ret

; __pb_round implements:
; 1. Compute scale = 10^places
; 2. scaled = num * scale
; 3. rounded = cvtsd2si(scaled + 0.5)
; 4. result = rounded / scale

See Also

  • INT
  • FIX


RND - PBXA64 Compiler Help

RND

Returns a pseudo-random number.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = RND
result = RND(n)
result = RND(lo, hi)

Description

RND generates pseudo-random numbers. With no argument or with a positive argument, it returns a DOUBLE in the range [0.0, 1.0). With two arguments, it returns a DOUBLE in the range [lo, hi). RND(0) returns the most recently generated value without generating a new one. The sequence is determined by the seed set with RANDOMIZE.

Parameters

Parameter | Description
n | Optional numeric argument. n > 0 generates a new value; n = 0 repeats the last value.
lo | Lower bound (inclusive) for the result range.
hi | Upper bound (exclusive) for the result range.

Examples

PRINT RND        ' prints a random number in [0.0, 1.0)
x = RND(1, 100)  ' x = random DOUBLE in [1.0, 100.0)
n = INT(RND(1, 7)) ' n = random integer 1 to 6 (dice roll)

Assembler Output

The compiler generates the following x64 code for this command:

; RND calls the runtime helper __imp_rand:
sub  rsp, 40
call __imp_rand   ; returns 32-bit random value in EAX
cvtsi2sd xmm0, eax
divsd xmm0, [rand_scale]  ; normalize to [0.0, 1.0)
add  rsp, 40
ret

See Also

  • RANDOMIZE


POW (^) - PBXA64 Compiler Help

POW (^)

Exponentiation operator — raises a base to an exponent power.

Kind: Function (Operator) | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = base ^ exponent

Description

The exponentiation operator (^) raises base to the power of exponent. Both operands are converted to DOUBLE for the calculation. The result is always a DOUBLE. Special cases: any base raised to 0 equals 1; 0 raised to any positive exponent equals 0.

Parameters

Parameter | Description
base | Numeric expression — the base value.
exponent | Numeric expression — the power to raise the base to.

Examples

PRINT 2 ^ 3      ' prints 8.0
PRINT 10 ^ -1    ' prints 0.1
PRINT 16 ^ 0.5   ' prints 4.0 (square root)
x = 5 ^ 2        ' x = 25.0

Assembler Output

The compiler generates the following x64 code for this command:

; POW calls the runtime helper __pb_pow_f64:
sub  rsp, 40
movsd xmm1, exponent   ; second arg in XMM1
movsd xmm0, base       ; first arg in XMM0
call __pb_pow_f64      ; result in XMM0
add  rsp, 40
ret

; __pb_pow_f64 internally calls:
; call __imp_pow   ; msvcrt pow(x, y)

See Also

  • EXP
  • SQR


TIMER - PBXA64 Compiler Help

TIMER

Returns the number of seconds elapsed since midnight as a DOUBLE.

Kind: Function | Category: Math

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = TIMER

Description

TIMER returns the number of seconds since midnight with approximately millisecond precision. The result is a DOUBLE. This is useful for elapsed time measurements, benchmarking, and seeding the random number generator.

Parameters

Parameter | Description
none | TIMER takes no arguments.

Examples

start! = TIMER
SLEEP 1000
elapsed! = TIMER - start!
PRINT "Elapsed seconds: "; elapsed!

RANDOMIZE TIMER

Assembler Output

The compiler generates the following x64 code for this command:

; TIMER calls GetLocalTime API:
sub  rsp, 56
lea  rcx, [rsp+8]     ; pointer to SYSTEMTIME struct
call GetLocalTime
movzx eax, word [rsp+8]    ; wHour
movzx ecx, word [rsp+10]   ; wMinute
movzx edx, word [rsp+12]   ; wSecond
movzx r8d, word [rsp+14]   ; wMilliseconds
; convert to seconds:
; result = hour*3600 + minute*60 + second + ms/1000.0
cvtsi2sd xmm0, eax
mulsd    xmm0, [3600_const]
cvtsi2sd xmm1, ecx
mulsd    xmm1, [60_const]
addsd    xmm0, xmm1
cvtsi2sd xmm1, edx
addsd    xmm0, xmm1
cvtsi2sd xmm1, r8d
divsd    xmm1, [1000_const]
addsd    xmm0, xmm1
add  rsp, 56
ret

See Also

  • DATE$
  • TIME$


IIF - PBXA64 Compiler Help

IIF

Immediate If — returns one of two values based on a condition.

Kind: Function | Category: Math / Conditional

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = IIF(condition, true_val, false_val)

Description

IIF evaluates condition as a boolean. If true, it evaluates and returns true_val; otherwise it evaluates and returns false_val. Both possible result values must be of the same type. Unlike IF/THEN/ELSE, IIF is an expression usable within any expression context.

Parameters

Parameter | Description
condition | Boolean expression evaluating to true (non-zero) or false (zero).
true_val | Value returned if condition is true.
false_val | Value returned if condition is false.

Examples

PRINT IIF(5 > 3, "yes", "no")  ' prints "yes"
x = IIF(n > 0, n, -n)          ' equivalent to ABS(n)
result = IIF(flag, 100, 0)     ' select based on flag

Assembler Output

The compiler generates the following x64 code for this command:

; IIF for integer types:
test rcx, rcx     ; test condition
cmovne rax, true_val   ; if condition true, use true_val
cmove  rax, false_val  ; if condition false, use false_val

; IIF for DOUBLE:
comisd xmm0, zero      ; compare condition
movsd  xmm2, true_val
movsd  xmm3, false_val
cmovne rax, xmm2       ; conditional move
cmove  rax, xmm3

See Also

  • IF / THEN / ELSE
  • CHOOSE
  • SWITCH


CHOOSE - PBXA64 Compiler Help

CHOOSE

Selects a value from a list by index.

Kind: Function | Category: Math / Conditional

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = CHOOSE(index, val1, val2, ...)

Description

CHOOSE returns the index-th value from the supplied argument list. If index = 1, val1 is returned; if index = 2, val2 is returned; and so on. If index is less than 1 or greater than the number of values, the result is 0 or an empty string depending on the type.

Parameters

Parameter | Description
index | Integer expression specifying which value to select (1-based).
val1, val2, ... | List of possible return values. All values must be of the same type.

Examples

dayname$ = CHOOSE(n, "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
grade$ = CHOOSE(score \ 10 + 1, "F","F","F","F","F","D","C","B","A","A")
PRINT CHOOSE(2, 100, 200, 300)  ' prints 200

Assembler Output

The compiler generates the following x64 code for this command:

; CHOOSE — index bounds check plus array-style lookup:
cmp  rcx, 1
jl   out_of_range
cmp  rcx, count
jg   out_of_range
dec  rcx            ; convert to 0-based
lea  rax, [value_table]
mov  rax, [rax + rcx*8]  ; indexed load
ret
out_of_range:
xor  eax, eax       ; return default (0)
ret

See Also

  • IIF
  • SWITCH
  • SELECT CASE


SWITCH - PBXA64 Compiler Help

SWITCH

Evaluates a series of condition-result pairs and returns the first matching result.

Kind: Function | Category: Math / Conditional

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = SWITCH(condition1, result1, condition2, result2, ...)

Description

SWITCH evaluates each condition in order. For the first condition that evaluates to true, the corresponding result is returned. If no condition is true, the result is 0 or an empty string depending on the return type.

Parameters

Parameter | Description
conditionN | Boolean expression.
resultN | Value returned if the corresponding condition is true.

Examples

grade$ = SWITCH(score >= 90, "A", score >= 80, "B", score >= 70, "C", score >= 60, "D", TRUE, "F")
result = SWITCH(n > 0, "positive", n < 0, "negative", TRUE, "zero")

Assembler Output

The compiler generates the following x64 code for this command:

; SWITCH — sequential test branches:
test condition1
jz   test2
mov  rax, result1
jmp  done
test2:
test condition2
jz   test3
mov  rax, result2
jmp  done
test3:
...
done:
ret

See Also

  • IIF
  • CHOOSE
  • SELECT CASE


CINT - PBXA64 Compiler Help

CINT

Converts a numeric expression to an INTEGER (2-byte signed).

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result% = CINT(num)

Description

CINT converts a numeric expression to a 16-bit signed INTEGER. For floating-point inputs, the value is rounded to the nearest integer using banker's rounding. For integer inputs larger than 16-bit range, the value is truncated to the lower 16 bits with sign extension. Range: -32768 to 32767. The compiler uses cvttsd2si (truncate) or cvtsd2si (round) for DOUBLE-to-INTEGER conversion.

Parameters

num — numeric expression to convert.

Parameters

Parameter | Description
num | Numeric expression of any type.

Examples

LOCAL i AS INTEGER
i = CINT(3.14159)    ' i = 3
i = CINT(-2.7)       ' i = -3 (banker's rounding)
i = CINT(65536)      ' i = 0 (truncation)

Assembler Output

; PBXA64 x64 assembly for CINT(double)
cvttsd2si eax, xmm0      ; truncate DOUBLE to 32-bit integer
mov [rbp-8], ax           ; store as 16-bit INTEGER

See Also

  • CLNG
  • CSNG
  • CDBL
  • CVI


CLNG - PBXA64 Compiler Help

CLNG

Converts a numeric expression to a LONG (4-byte signed).

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = CLNG(num)

Description

CLNG converts a numeric expression to a 32-bit signed LONG. For floating-point inputs, the value is rounded using banker's rounding. For integer inputs exceeding 32-bit range, the value is truncated to the lower 32 bits. Range: -2147483648 to 2147483647. The compiler uses cvttsd2si for truncation or cvtsd2si for rounding from DOUBLE.

Parameters

num — numeric expression to convert.

Parameters

Parameter | Description
num | Numeric expression of any type.

Examples

LOCAL l AS LONG
l = CLNG(3.14159)     ' l = 3
l = CLNG(100000)      ' l = 100000

Assembler Output

; PBXA64 x64 assembly for CLNG(double)
cvttsd2si eax, xmm0     ; truncate/cvt DOUBLE to LONG
mov [rbp-8], eax         ; store as 32-bit LONG

See Also

  • CINT
  • CSNG
  • CDBL
  • CVL


CSNG - PBXA64 Compiler Help

CSNG

Converts a numeric expression to a SINGLE (4-byte floating-point).

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result! = CSNG(num)

Description

CSNG converts a numeric expression to a 32-bit IEEE 754 SINGLE-precision float. For DOUBLE inputs, the value is converted with possible loss of precision (approximately 7 significant digits). For integer inputs, the value is converted to the nearest float representation. Range: approximately ±1.5 x 10^-45 to ±3.4 x 10^38. The compiler uses cvtsd2ss to convert from DOUBLE to SINGLE.

Parameters

num — numeric expression to convert.

Parameters

Parameter | Description
num | Numeric expression of any type.

Examples

LOCAL s AS SINGLE
s = CSNG(3.14159265358979)   ' s = 3.141593 (precision loss)
s = CSNG(100)                ' s = 100.0

Assembler Output

; PBXA64 x64 assembly for CSNG(double)
cvtsd2ss xmm0, xmm0      ; convert DOUBLE in XMM0 to SINGLE
movss [rbp-4], xmm0       ; store as 32-bit float

See Also

  • CDBL
  • CINT
  • CLNG
  • CVS


CDBL - PBXA64 Compiler Help

CDBL

Converts a numeric expression to a DOUBLE (8-byte floating-point).

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result# = CDBL(num)

Description

CDBL converts a numeric expression to a 64-bit IEEE 754 DOUBLE-precision float. For SINGLE inputs, the value is promoted to DOUBLE with no precision loss. For integer inputs, exact conversion is possible up to 2^53. If the input is already DOUBLE, the conversion is a no-op. Range: approximately ±5.0 x 10^-324 to ±1.7 x 10^308. The compiler uses cvtss2sd for SINGLE-to-DOUBLE conversion.

Parameters

num — numeric expression to convert.

Parameters

Parameter | Description
num | Numeric expression of any type.

Examples

LOCAL d AS DOUBLE
d = CDBL(3.14159)       ' 3.14159 (already DOUBLE, no-op)
d = CDBL(100)           ' 100.0

Assembler Output

; PBXA64 x64 assembly for CDBL(single)
cvtss2sd xmm0, xmm0      ; promote SINGLE to DOUBLE
movsd [rbp-8], xmm0       ; store as 64-bit DOUBLE

; CDBL from DOUBLE: no instruction generated

See Also

  • CSNG
  • CINT
  • CLNG
  • CVD


VALI - PBXA64 Compiler Help

VALI

Converts a string to a QUAD (64-bit signed integer).

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result&& = VALI(str)

Description

VALI converts a string to a 64-bit signed QUAD integer. Leading whitespace is skipped. An optional leading + or - sign is allowed. Digits are accumulated until a non-digit character is encountered. If the string does not contain a valid integer, VALI returns 0. The runtime helper calls _atoi64 (MSVC CRT) to perform the conversion. Range: -9223372036854775808 to 9223372036854775807.

Parameters

str — string expression containing an integer representation.

Parameters

Parameter | Description
str | String containing a decimal integer.

Examples

LOCAL q AS QUAD
q = VALI("1234567890123")     ' q = 1234567890123
q = VALI("  -42")             ' q = -42
q = VALI("abc")               ' q = 0

Assembler Output

; PBXA64 x64 assembly for VALI
lea rcx, [rbp-32]           ; PB_STRING64 descriptor address
call __pb_vali               ; call VALI runtime helper
; Internal: calls _atoi64(string_data_ptr)
mov [rbp-8], rax             ; store QUAD result

See Also

  • VAL
  • VALD
  • STR$


VALD - PBXA64 Compiler Help

VALD

Converts a string to a DOUBLE (8-byte floating-point).

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result# = VALD(str)

Description

VALD converts a string to a 64-bit DOUBLE-precision floating-point value. Leading whitespace is skipped. An optional leading sign, decimal point, and exponent (E/e) are parsed. If the string does not contain a valid floating-point number, VALD returns 0. The runtime helper calls atof (MSVC CRT) to perform the conversion. VALD is the preferred function for generic string-to-number conversion when the result type is DOUBLE.

Parameters

str — string expression containing a numeric representation.

Parameters

Parameter | Description
str | String containing a floating-point number.

Examples

LOCAL d AS DOUBLE
d = VALD("3.14159")        ' d = 3.14159
d = VALD("  -2.5e-3")      ' d = -0.0025
d = VALD("not a number")   ' d = 0

Assembler Output

; PBXA64 x64 assembly for VALD
lea rcx, [rbp-32]           ; PB_STRING64 descriptor address
call __pb_vald               ; call VALD runtime helper
; Internal: calls atof(string_data_ptr)
movsd [rbp-8], xmm0         ; store DOUBLE result

See Also

  • VAL
  • VALI
  • STR$


MKBYT$ - PBXA64 Compiler Help

MKBYT$

Converts a BYTE value to a 1-character binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKBYT$(byte)

Description

MKBYT$ creates a 1-byte binary string containing the specified BYTE value. The resulting string has a length of 1 and contains the raw byte value. This is the inverse of CVBYT. Binary strings are used for random-access file I/O and for storing numeric values in string variables for binary manipulation. The runtime allocates a 1-character PB_STRING64 and copies the byte value.

Parameters

byte — BYTE value (0-255) to convert.

Parameters

Parameter | Description
byte | BYTE expression (0-255).

Examples

LOCAL s AS STRING
s = MKBYT$(65)     ' s = CHR$(65) = "A"
s = MKBYT$(0)      ' s = CHR$(0)

Assembler Output

; PBXA64 x64 assembly for MKBYT$
mov rcx, [rbp-8]           ; BYTE value (zero-extended)
call __pb_mkbyt             ; allocates 1-byte string, stores byte
mov [rbp-32], rax           ; store PB_STRING64 descriptor

See Also

  • CVBYT
  • MKI$
  • MKL$


MKI$ - PBXA64 Compiler Help

MKI$

Converts an INTEGER value to a 2-character binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKI$(int)

Description

MKI$ creates a 2-byte binary string containing the bytes of a 16-bit signed INTEGER value. The bytes are stored in little-endian order (low byte first). This is the inverse of CVI. The resulting string has a length of 2. Binary strings are used for random-access file I/O and for storing numeric values in binary format.

Parameters

int — INTEGER value (-32768 to 32767) to convert.

Parameters

Parameter | Description
int | INTEGER expression to convert.

Examples

LOCAL s AS STRING
s = MKI$(12345)     ' 2-byte binary string
s = MKI$(-1)        ' CHR$(&HFF) + CHR$(&HFF)

Assembler Output

; PBXA64 x64 assembly for MKI$
mov rcx, [rbp-8]           ; INTEGER value (word)
call __pb_mki               ; allocates 2-byte string, stores word
mov [rbp-32], rax           ; store PB_STRING64 descriptor

See Also

  • CVI
  • MKL$
  • MKBYT$


MKL$ - PBXA64 Compiler Help

MKL$

Converts a LONG value to a 4-character binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKL$(long)

Description

MKL$ creates a 4-byte binary string containing the bytes of a 32-bit signed LONG value. The bytes are stored in little-endian order. This is the inverse of CVL. The resulting string has a length of 4. Binary strings are used for random-access file I/O and for storing numeric values in binary format for external APIs or data structures.

Parameters

long — LONG value (-2147483648 to 2147483647) to convert.

Parameters

Parameter | Description
long | LONG expression to convert.

Examples

LOCAL s AS STRING
s = MKL$(100000)     ' 4-byte binary string
s = MKL$(-1)         ' CHR$(&HFF) x 4

Assembler Output

; PBXA64 x64 assembly for MKL$
mov rcx, [rbp-8]           ; LONG value (dword)
call __pb_mkl               ; allocates 4-byte string, stores dword
mov [rbp-32], rax           ; store PB_STRING64 descriptor

See Also

  • CVL
  • MKDWD$
  • MKI$


MKDWD$ - PBXA64 Compiler Help

MKDWD$

Converts a DWORD value to a 4-character binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKDWD$(dword)

Description

MKDWD$ creates a 4-byte binary string containing the bytes of a 32-bit unsigned DWORD value. The bytes are stored in little-endian order. This is the inverse of CVDWD. The resulting string has a length of 4. Unlike MKL$, MKDWD$ treats the input as unsigned. Binary strings are used for random-access file I/O and binary data manipulation.

Parameters

dword — DWORD value (0 to 4294967295) to convert.

Parameters

Parameter | Description
dword | DWORD expression to convert.

Examples

LOCAL s AS STRING
s = MKDWD$(4000000000)   ' 4-byte unsigned binary string

Assembler Output

; PBXA64 x64 assembly for MKDWD$
mov rcx, [rbp-8]           ; DWORD value (dword, zero-extended)
call __pb_mkdwd             ; allocates 4-byte string, stores dword
mov [rbp-32], rax           ; store PB_STRING64 descriptor

See Also

  • CVDWD
  • MKL$
  • MKQ$


MKQ$ - PBXA64 Compiler Help

MKQ$

Converts a QUAD value to an 8-character binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKQ$(quad)

Description

MKQ$ creates an 8-byte binary string containing the bytes of a 64-bit signed QUAD value. The bytes are stored in little-endian order. This is the inverse of CVQ. The resulting string has a length of 8. Binary strings are used for random-access file I/O and for storing large integer values in binary format.

Parameters

quad — QUAD value to convert.

Parameters

Parameter | Description
quad | QUAD expression to convert.

Examples

LOCAL s AS STRING
s = MKQ$(1234567890123)   ' 8-byte binary string

Assembler Output

; PBXA64 x64 assembly for MKQ$
mov rcx, [rbp-8]           ; QUAD value (qword)
call __pb_mkq               ; allocates 8-byte string, stores qword
mov [rbp-32], rax           ; store PB_STRING64 descriptor

See Also

  • CVQ
  • MKL$
  • MKD$


MKS$ - PBXA64 Compiler Help

MKS$

Converts a SINGLE value to a 4-character IEEE binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKS$(single)

Description

MKS$ creates a 4-byte binary string containing the IEEE 754 single-precision representation of a SINGLE value. The bytes are stored in little-endian order. This is the inverse of CVS. The resulting string has a length of 4. The binary representation preserves the exact bit pattern of the floating-point value, including sign, exponent, and mantissa.

Parameters

single — SINGLE value to convert.

Parameters

Parameter | Description
single | SINGLE expression to convert.

Examples

LOCAL s AS STRING
s = MKS$(3.14159)     ' 4-byte IEEE 754 binary representation

Assembler Output

; PBXA64 x64 assembly for MKS$
movss xmm0, [rbp-8]        ; load SINGLE value
call __pb_mks               ; allocates 4-byte string, stores bits
mov [rbp-32], rax           ; store PB_STRING64 descriptor

See Also

  • CVS
  • MKD$
  • MKL$


MKD$ - PBXA64 Compiler Help

MKD$

Converts a DOUBLE value to an 8-character IEEE binary string.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

s$ = MKD$(double)

Description

MKD$ creates an 8-byte binary string containing the IEEE 754 double-precision representation of a DOUBLE value. The bytes are stored in little-endian order. This is the inverse of CVD. The resulting string has a length of 8. The binary representation preserves the exact bit pattern of the floating-point value, including sign, exponent, and mantissa.

Parameters

double — DOUBLE value to convert.

Parameters

Parameter | Description
double | DOUBLE expression to convert.

Examples

LOCAL s AS STRING
s = MKD$(3.14159265358979)   ' 8-byte IEEE 754 binary representation

Assembler Output

; PBXA64 x64 assembly for MKD$
movsd xmm0, [rbp-8]         ; load DOUBLE value
call __pb_mkd                ; allocates 8-byte string, stores bits
mov [rbp-32], rax            ; store PB_STRING64 descriptor

See Also

  • CVD
  • MKS$
  • MKQ$


CVBYT - PBXA64 Compiler Help

CVBYT

Converts a 1-character binary string to a BYTE value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

byte = CVBYT(str)

Description

CVBYT extracts a BYTE value from the first character of a binary string. This is the inverse of MKBYT$. The string should have been created by MKBYT$ or contain at least 1 byte; if the string is empty, the result is 0. CVBYT reads the first byte of the string's data buffer and returns it as a zero-extended BYTE (0-255).

Parameters

str — string expression containing at least 1 byte of binary data.

Parameters

Parameter | Description
str | Binary string (1 or more bytes).

Examples

LOCAL b AS BYTE
b = CVBYT(MKBYT$(65))    ' b = 65
b = CVBYT(CHR$(255))     ' b = 255

Assembler Output

; PBXA64 x64 assembly for CVBYT
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
movzx eax, byte [rax]      ; load first byte, zero-extend
mov [rbp-8], al            ; store BYTE result

See Also

  • MKBYT$
  • CVI
  • CVL


CVI - PBXA64 Compiler Help

CVI

Converts a 2-character binary string to an INTEGER value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

int% = CVI(str)

Description

CVI extracts a 16-bit signed INTEGER from the first 2 bytes of a binary string (little-endian). This is the inverse of MKI$. If the string has fewer than 2 bytes, the result is undefined. CVI reads a word from the string's data buffer and sign-extends it to the register width.

Parameters

str — string expression containing at least 2 bytes of binary data.

Parameters

Parameter | Description
str | Binary string (2 or more bytes).

Examples

LOCAL i AS INTEGER
i = CVI(MKI$(12345))   ' i = 12345
i = CVI(MKI$(-1))      ' i = -1

Assembler Output

; PBXA64 x64 assembly for CVI
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
movsx eax, word [rax]      ; load word, sign-extend
mov [rbp-8], ax            ; store INTEGER result

See Also

  • MKI$
  • CVL
  • CVBYT


CVL - PBXA64 Compiler Help

CVL

Converts a 4-character binary string to a LONG value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

long& = CVL(str)

Description

CVL extracts a 32-bit signed LONG from the first 4 bytes of a binary string (little-endian). This is the inverse of MKL$. If the string has fewer than 4 bytes, the result is undefined. CVL reads a dword from the string's data buffer and sign-extends it to 64 bits.

Parameters

str — string expression containing at least 4 bytes of binary data.

Parameters

Parameter | Description
str | Binary string (4 or more bytes).

Examples

LOCAL l AS LONG
l = CVL(MKL$(100000))   ' l = 100000
l = CVL(MKL$(-1))       ' l = -1

Assembler Output

; PBXA64 x64 assembly for CVL
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
mov eax, [rax]             ; load dword (zero-extends to 64-bit)
mov [rbp-8], eax           ; store LONG result

See Also

  • MKL$
  • CVDWD
  • CVI


CVDWD - PBXA64 Compiler Help

CVDWD

Converts a 4-character binary string to a DWORD value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

dword = CVDWD(str)

Description

CVDWD extracts a 32-bit unsigned DWORD from the first 4 bytes of a binary string (little-endian). This is the inverse of MKDWD$. Unlike CVL, CVDWD treats the result as unsigned. If the string has fewer than 4 bytes, the result is undefined. CVDWD reads a dword from the string's data buffer.

Parameters

str — string expression containing at least 4 bytes of binary data.

Parameters

Parameter | Description
str | Binary string (4 or more bytes).

Examples

LOCAL dw AS DWORD
dw = CVDWD(MKDWD$(4000000000))   ' dw = 4000000000

Assembler Output

; PBXA64 x64 assembly for CVDWD
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
mov eax, [rax]             ; load dword (zero-extends)
mov [rbp-8], eax           ; store DWORD result

See Also

  • MKDWD$
  • CVL
  • CVQ


CVQ - PBXA64 Compiler Help

CVQ

Converts an 8-character binary string to a QUAD value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

quad&& = CVQ(str)

Description

CVQ extracts a 64-bit signed QUAD from the first 8 bytes of a binary string (little-endian). This is the inverse of MKQ$. If the string has fewer than 8 bytes, the result is undefined. CVQ reads a qword from the string's data buffer.

Parameters

str — string expression containing at least 8 bytes of binary data.

Parameters

Parameter | Description
str | Binary string (8 or more bytes).

Examples

LOCAL q AS QUAD
q = CVQ(MKQ$(1234567890123))   ' q = 1234567890123

Assembler Output

; PBXA64 x64 assembly for CVQ
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
mov rax, [rax]             ; load qword
mov [rbp-8], rax           ; store QUAD result

See Also

  • MKQ$
  • CVD
  • CVL


CVS - PBXA64 Compiler Help

CVS

Converts a 4-character IEEE binary string to a SINGLE value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

single! = CVS(str)

Description

CVS extracts a 32-bit IEEE 754 single-precision float from the first 4 bytes of a binary string (little-endian). This is the inverse of MKS$. If the string has fewer than 4 bytes, the result is undefined. CVS reads the bit pattern from the data buffer and interprets it as a float.

Parameters

str — string expression containing at least 4 bytes of IEEE binary data.

Parameters

Parameter | Description
str | Binary string (4 or more bytes).

Examples

LOCAL s AS SINGLE
s = CVS(MKS$(3.14159))   ' s = 3.14159

Assembler Output

; PBXA64 x64 assembly for CVS
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
movss xmm0, [rax]          ; load 4-byte IEEE float
movss [rbp-4], xmm0        ; store SINGLE result

See Also

  • MKS$
  • CVD
  • CSNG


CVD - PBXA64 Compiler Help

CVD

Converts an 8-character IEEE binary string to a DOUBLE value.

Kind: Function | Category: Type Conversion

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

double# = CVD(str)

Description

CVD extracts a 64-bit IEEE 754 double-precision float from the first 8 bytes of a binary string (little-endian). This is the inverse of MKD$. If the string has fewer than 8 bytes, the result is undefined. CVD reads the bit pattern from the data buffer and interprets it as a DOUBLE.

Parameters

str — string expression containing at least 8 bytes of IEEE binary data.

Parameters

Parameter | Description
str | Binary string (8 or more bytes).

Examples

LOCAL d AS DOUBLE
d = CVD(MKD$(3.14159265358979))   ' d = 3.14159265358979

Assembler Output

; PBXA64 x64 assembly for CVD
mov rax, [rbp-32]          ; load PB_STRING64 descriptor
mov rax, [rax]             ; read data pointer
movsd xmm0, [rax]          ; load 8-byte IEEE double
movsd [rbp-8], xmm0        ; store DOUBLE result

See Also

  • MKD$
  • CVS
  • CDBL


IF / THEN / ELSE - PBXA64 Compiler Help

IF / THEN / ELSE

Conditional execution — evaluates a boolean expression and executes statements accordingly.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

IF condition THEN statements [ELSE statements]

IF condition THEN
    statements
[ELSE
    statements]
END IF

Description

IF evaluates condition. If it is true (non-zero), the statements after THEN are executed. If false and an ELSE clause is present, the statements after ELSE are executed. The single-line form puts everything on one line with no END IF. The block form supports multiple lines and requires END IF.

Parameters

Parameter | Description
condition | Boolean expression. Treated as true if non-zero, false if zero.
statements | One or more statements to execute conditionally.

Examples

IF x > 0 THEN PRINT "positive"

IF score >= 90 THEN
    grade = "A"
ELSEIF score >= 80 THEN
    grade = "B"
ELSE
    grade = "F"
END IF

Assembler Output

The compiler generates the following x64 code for this command:

; IF condition THEN ... ELSE ...:
test rcx, rcx        ; evaluate condition
jz   else_label      ; jump if false
; ... true branch code ...
jmp  end_label
else_label:
; ... false branch code ...
end_label:

See Also

  • SELECT CASE
  • IIF


SELECT CASE - PBXA64 Compiler Help

SELECT CASE

Multi-branch conditional execution based on the value of an expression.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SELECT CASE expression
    CASE value1 [, value2 ...]
        statements
    CASE value3 TO value4
        statements
    CASE IS comparison_op value5
        statements
    CASE ELSE
        statements
END SELECT

Description

SELECT CASE evaluates expression once, then compares it against each CASE clause in order. The first matching CASE executes its statements. CASE clauses can specify individual values, ranges (TO), or relational conditions (IS >, IS <, etc.). If no CASE matches and CASE ELSE is present, its statements execute.

Parameters

Parameter | Description
expression | Numeric or string expression to evaluate.
valueN | Match value or list of values.
comparison_op | One of: =, <>, <, >, <=, >=.

Examples

SELECT CASE n
    CASE 1
        PRINT "one"
    CASE 2, 3, 5, 7
        PRINT "prime"
    CASE 10 TO 20
        PRINT "between 10 and 20"
    CASE IS > 100
        PRINT "large"
    CASE ELSE
        PRINT "other"
END SELECT

Assembler Output

The compiler generates the following x64 code for this command:

; SELECT CASE — register compare with jump table for contiguous ranges:
cmp  rcx, 1
je   case_1
cmp  rcx, 2
je   case_2
cmp  rcx, 3
je   case_3
...
jmp  case_else

; For dense ranges, the compiler may emit a jump table:
lea  rdx, [jump_table]
mov  rax, [rdx + rcx*8]
jmp  rax

See Also

  • IF / THEN / ELSE
  • CHOOSE


FOR / NEXT - PBXA64 Compiler Help

FOR / NEXT

Counted loop — repeats a block of statements a specified number of times.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

FOR var = start TO end [STEP increment]
    statements
NEXT [var]

Description

FOR initialises var to start, then executes the loop body. After each iteration, var is increased by increment (default = 1). The loop continues while var ≤ end (for positive STEP) or var ≥ end (for negative STEP). The loop variable must be a numeric variable.

Parameters

Parameter | Description
var | Numeric loop variable (LONG, QUAD, or DOUBLE).
start | Initial value for the loop variable.
end | Final value. Loop terminates when var passes end.
increment | Optional STEP value (default 1). Can be negative.

Examples

FOR i = 1 TO 10
    PRINT i
NEXT

FOR n = 20 TO 2 STEP -2
    PRINT n
NEXT

total = 0
FOR x = 1 TO 100
    total = total + x
NEXT

Assembler Output

The compiler generates the following x64 code for this command:

; FOR initialisation:
mov  [var], start_value
; loop_start:
; ... loop body ...
; loop_increment:
mov  rax, [var]
add  rax, step_value
mov  [var], rax
cmp  rax, end_value
jle  loop_start     ; for positive STEP
; loop_end:

See Also

  • WHILE / WEND
  • DO / LOOP
  • EXIT
  • ITERATE


WHILE / WEND - PBXA64 Compiler Help

WHILE / WEND

Conditional loop — repeats while a condition is true.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

WHILE condition
    statements
WEND

Description

WHILE evaluates condition before each iteration. If the condition is true (non-zero), the loop body executes. The loop repeats until the condition becomes false. If the condition is false from the start, the body never executes.

Parameters

Parameter | Description
condition | Boolean expression evaluated before each iteration.

Examples

x = 10
WHILE x > 0
    PRINT x
    x = x - 1
WEND

WHILE NOT EOF(1)
    LINE INPUT #1, line$
    PRINT line$
WEND

Assembler Output

The compiler generates the following x64 code for this command:

; WHILE:
jmp  loop_test
loop_start:
; ... loop body ...
loop_test:
test rcx, rcx       ; evaluate condition
jnz  loop_start     ; if true, continue
; loop_end:

See Also

  • FOR / NEXT
  • DO / LOOP


DO / LOOP - PBXA64 Compiler Help

DO / LOOP

Flexible conditional loop with pre-test or post-test.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

DO [{WHILE | UNTIL} condition]
    statements
LOOP [{WHILE | UNTIL} condition]

Description

DO/LOOP provides flexible loop control. With no clause, it creates an infinite loop (use EXIT DO to terminate). WHILE repeats while the condition is true. UNTIL repeats until the condition becomes true (i.e. while false). The condition can be tested at the top (after DO) or at the bottom (after LOOP), or both.

Parameters

Parameter | Description
condition | Boolean expression to test.

Examples

' Pre-test:
DO WHILE x > 0
    PRINT x
    x = x - 1
LOOP

' Post-test (body always runs at least once):
DO
    LINE INPUT #1, line$
    PRINT line$
LOOP UNTIL EOF(1)

' Infinite loop with EXIT:
DO
    INPUT "Enter Q to quit: ", s$
    IF UCASE$(s$) = "Q" THEN EXIT DO
LOOP

Assembler Output

The compiler generates the following x64 code for this command:

; DO WHILE (pre-test):
jmp  loop_test
loop_start:
; ... loop body ...
loop_test:
test rcx, rcx       ; evaluate condition
jnz  loop_start     ; if true, continue

; DO ... LOOP UNTIL (post-test):
loop_start:
; ... loop body ...
loop_test:
test rcx, rcx       ; evaluate condition
jz   loop_start     ; if false (not yet true), continue

See Also

  • FOR / NEXT
  • WHILE / WEND
  • EXIT
  • ITERATE


GOTO - PBXA64 Compiler Help

GOTO

Unconditional jump to a program label.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

GOTO label

Description

GOTO transfers program execution unconditionally to the statement following the specified label. The label must exist within the same function or subroutine. GOTO is useful for error handling, breaking out of deeply nested loops, and implementing finite-state machines.

Parameters

Parameter | Description
label | Target label name. Must be defined elsewhere in the same scope.

Examples

IF error THEN GOTO errhandler
PRINT "OK"
GOTO done
errhandler:
PRINT "error!"
done:
' continue

Assembler Output

The compiler generates the following x64 code for this command:

; GOTO label:
jmp  label     ; unconditional near jump

See Also

  • GOSUB / RETURN
  • LABEL


GOSUB / RETURN - PBXA64 Compiler Help

GOSUB / RETURN

Subroutine call and return within a function or procedure.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

GOSUB label
...
label:
    statements
    RETURN

Description

GOSUB jumps to label and pushes the return address onto an internal stack. The subroutine executes until a RETURN statement, at which point execution resumes at the statement following the original GOSUB. Unlike CALL, GOSUB does not pass parameters and the subroutine shares all local variables with the caller.

Parameters

Parameter | Description
label | Target label within the same function or procedure.

Examples

GOSUB display_help
' ... main code ...

display_help:
PRINT "Usage: myprog [options]"
PRINT "  -h  show help"
PRINT "  -v  verbose"
RETURN

Assembler Output

The compiler generates the following x64 code for this command:

; GOSUB label:
call label      ; push return address and jump

; label:
; ... subroutine body ...
ret             ; pop return address and jump back

See Also

  • GOTO
  • CALL
  • LABEL


EXIT - PBXA64 Compiler Help

EXIT

Prematurely exits a loop, function, or subroutine.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

EXIT FOR
EXIT DO
EXIT WHILE
EXIT FUNCTION
EXIT SUB
EXIT HANDLER

Description

EXIT immediately terminates the specified construct and transfers control to the statement after its end. EXIT FOR, EXIT DO, and EXIT WHILE exit the respective loop. EXIT FUNCTION and EXIT SUB return from the current function or subroutine early. EXIT HANDLER exits an error handler.

Parameters

Parameter | Description
FOR | Exits the innermost FOR/NEXT loop.
DO | Exits the innermost DO/LOOP loop.
WHILE | Exits the innermost WHILE/WEND loop.
FUNCTION | Returns from the current FUNCTION.
SUB | Returns from the current SUB.
HANDLER | Exits the current error handler.

Examples

FOR i = 1 TO 100
    IF array(i) = target THEN
        found = i
        EXIT FOR
    END IF
NEXT

DO
    INPUT "Enter Q to quit: ", cmd$
    IF UCASE$(cmd$) = "Q" THEN EXIT DO
LOOP

Assembler Output

The compiler generates the following x64 code for this command:

; EXIT FOR / EXIT DO / EXIT WHILE:
jmp loop_end_label   ; jump to the end of the loop

; EXIT FUNCTION:
; ... cleanup local variables ...
ret

; EXIT SUB:
; ... cleanup local variables ...
ret

See Also

  • ITERATE
  • FOR / NEXT
  • DO / LOOP


ITERATE - PBXA64 Compiler Help

ITERATE

Skips the remainder of the current loop iteration and continues with the next iteration.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ITERATE {FOR | DO}

Description

ITERATE jumps to the loop variable increment (FOR) or condition test (DO/WHILE) of the innermost loop of the specified type, skipping any remaining statements in the current iteration. It is analogous to continue in C-like languages.

Parameters

Parameter | Description
FOR | Skips to the NEXT increment of the innermost FOR/NEXT loop.
DO | Skips to the LOOP test of the innermost DO/LOOP loop.

Examples

FOR i = 1 TO 10
    IF i MOD 2 = 0 THEN ITERATE FOR  ' skip even numbers
    PRINT i                           ' prints only odds
NEXT

DO WHILE NOT EOF(1)
    LINE INPUT #1, line$
    IF line$ = "" THEN ITERATE DO    ' skip blank lines
    PRINT line$
LOOP

Assembler Output

The compiler generates the following x64 code for this command:

; ITERATE FOR:
jmp loop_increment   ; jump to FOR increment code

; ITERATE DO:
jmp loop_test        ; jump to DO/LOOP condition test

See Also

  • EXIT
  • FOR / NEXT
  • DO / LOOP


CALL - PBXA64 Compiler Help

CALL

Calls a SUB procedure, optionally passing arguments.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

CALL subname [ (arg1, arg2, ...) ]

subname [arg1, arg2, ...]    ' implicit CALL (no parentheses)

Description

CALL invokes a SUB procedure (not a FUNCTION). Arguments are passed by reference by default, or by value using the BYVAL keyword. The parentheses are optional when CALL is used explicitly; without CALL, arguments must not be wrapped in parentheses (to distinguish from function calls).

Parameters

Parameter | Description
subname | Name of the SUB to call.
argN | Optional arguments passed to the SUB.

Examples

CALL MySub(a, b, c)
MySub a, b, c          ' implicit CALL
CALL ShowHelp()

Assembler Output

The compiler generates the following x64 code for this command:

; CALL subname(args) — x64 calling convention:
sub  rsp, 40          ; allocate shadow space
mov  rcx, arg1        ; first argument in RCX
mov  rdx, arg2        ; second argument in RDX
mov  r8,  arg3        ; third argument in R8
mov  r9,  arg4        ; fourth argument in R9
; remaining args on stack
call subname
add  rsp, 40          ; deallocate shadow space

See Also

  • GOSUB / RETURN
  • FUNCTION
  • SUB


LABEL - PBXA64 Compiler Help

LABEL

Defines a target location for GOTO or GOSUB.

Kind: Statement | Category: Control Flow

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

labelname:

Description

A label is a user-defined name followed by a colon that marks a location in the program. Labels are targets for GOTO and GOSUB statements. Label names follow identifier naming rules and must be unique within the same scope.

Parameters

Parameter | Description
labelname | Valid identifier followed by a colon. Must start with a letter or underscore.

Examples

start:
    PRINT "Enter command:"
    INPUT cmd$
    IF cmd$ = "help" THEN GOTO showhelp
    GOTO done
showhelp:
    PRINT "Commands: help, quit"
    GOTO start
done:
    PRINT "Done"

Assembler Output

The compiler generates the following x64 code for this command:

A label is a target for jumps and calls. No instructions are emitted for the label itself — it is a symbolic address in the assembly listing.

; label:   ← no code emitted, just marks a location
; ... next instruction ...

See Also

  • GOTO
  • GOSUB / RETURN


ON ERROR - PBXA64 Compiler Help

ON ERROR

Sets the runtime error handling mode.

Kind: Statement | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ON ERROR GOTO label
ON ERROR RESUME NEXT
ON ERROR GOTO 0

Description

ON ERROR configures how runtime errors are handled. ON ERROR GOTO label sets the error handler to a specific label; when a runtime error occurs, execution jumps to the label and the error code is stored in ERR and ERL. ON ERROR RESUME NEXT instructs the runtime to continue execution at the statement following the one that caused the error. ON ERROR GOTO 0 disables the current error handler; subsequent runtime errors will terminate the program. The runtime stores the handler address in __pb_err_handler and the resume mode in __pb_err_mode.

Parameters

label — label name to jump to on error.
RESUME NEXT — continue at next statement after error.
GOTO 0 — disable error handling.

Parameters

Mode | Description
GOTO label | Jump to label when error occurs.
RESUME NEXT | Skip the failing statement and continue.
GOTO 0 | Disable error handling, allow termination.

Examples

ON ERROR GOTO ErrorHandler
OPEN "missing.txt" FOR INPUT AS #1
' ...
EXIT SUB
ErrorHandler:
  PRINT "Error"; ERR; "at line"; ERL
  RESUME NEXT

Assembler Output

; PBXA64 x64 assembly for ON ERROR GOTO label
lea rax, [ErrorHandler]    ; load handler label address
mov [__pb_err_handler], rax ; store in global handler pointer
mov [__pb_err_mode], 0      ; 0 = GOTO mode

; ON ERROR RESUME NEXT
mov [__pb_err_mode], 1      ; 1 = RESUME NEXT mode
mov [__pb_err_handler], 0   ; no handler label

; ON ERROR GOTO 0
mov [__pb_err_handler], 0   ; clear handler
mov [__pb_err_mode], 0

See Also

  • RESUME
  • ERROR
  • ERR
  • ERL
  • ERRCLEAR


ERROR - PBXA64 Compiler Help

ERROR

Simulates a runtime error with a specified error code.

Kind: Statement | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ERROR code

Description

ERROR simulates a runtime error by setting the error code and transferring control to the current error handler. The runtime stores the specified code (must be non-zero) in __pb_err and the current source line number in __pb_erl. If an ON ERROR GOTO handler is active, execution jumps to the handler label. If ON ERROR RESUME NEXT is active, execution continues at the next statement. If no handler is active (ON ERROR GOTO 0), the program is terminated.

Parameters

code — numeric error code to simulate (must be non-zero).

Parameters

Parameter | Description
code | Error code (1-65535). Non-zero values only.

Examples

ON ERROR GOTO Handler
ERROR 5      ' simulate error code 5
PRINT "This won't print"
Handler:
  PRINT "Error"; ERR; "simulated"
  RESUME NEXT

Assembler Output

; PBXA64 x64 assembly for ERROR
mov [__pb_err], 5           ; store error code
mov rax, [rip+__pb_current_line]
mov [__pb_erl], rax         ; store line number
mov rax, [__pb_err_handler] ; load handler address
test rax, rax
jz __pb_fatal_error         ; if no handler, terminate
jmp rax                     ; jump to handler

See Also

  • ON ERROR
  • RESUME
  • ERR
  • ERRCLEAR


RESUME - PBXA64 Compiler Help

RESUME

Continues execution after an error has been handled.

Kind: Statement | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

RESUME
RESUME NEXT
RESUME label

Description

RESUME continues program execution after a runtime error has been handled. RESUME (without qualifier) re-executes the statement that caused the error. RESUME NEXT continues execution at the statement immediately following the one that caused the error. RESUME label continues execution at the specified label. The runtime stores the appropriate resume address in __pb_resume_addr which is set by the error handler dispatching logic. After RESUME, the ERR and ERL values are automatically cleared.

Parameters

label — label to resume execution at.

Parameters

Form | Description
RESUME | Re-execute the failed statement.
RESUME NEXT | Continue at the next statement.
RESUME label | Continue at the specified label.

Examples

ON ERROR GOTO Handler
OPEN "data.txt" FOR INPUT AS #1
' ...
EXIT SUB
Handler:
  PRINT "File not found, creating..."
  OPEN "data.txt" FOR OUTPUT AS #1
  RESUME               ' re-execute the OPEN statement

Assembler Output

; PBXA64 x64 assembly for RESUME
xor eax, eax
mov [__pb_err], eax        ; clear error code
mov [__pb_erl], eax        ; clear error line
; jmp to saved resume address (set by error dispatching)
mov rax, [__pb_resume_addr]
jmp rax

; RESUME NEXT: resume at instruction after failing one
; RESUME label: resume at specific label address

See Also

  • ON ERROR
  • ERROR
  • ERRCLEAR
  • ERR


ERRCLEAR - PBXA64 Compiler Help

ERRCLEAR

Clears the current error code and error line number.

Kind: Statement | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ERRCLEAR

Description

ERRCLEAR resets the runtime error state by setting both ERR and ERL to zero. This is useful to clear a previous error condition before performing further operations that might generate their own errors. After ERRCLEAR, ERR returns 0 and ERL returns 0 until the next error occurs. ERRCLEAR does not change the current error handler configuration set by ON ERROR.

Examples

ON ERROR GOTO Handler
OPEN "test.txt" FOR INPUT AS #1
IF ERR THEN
  PRINT "Error"; ERR
  ERRCLEAR
  OPEN "default.txt" FOR INPUT AS #1
END IF

Assembler Output

; PBXA64 x64 assembly for ERRCLEAR
xor eax, eax
mov [__pb_err], eax        ; clear error code
mov [__pb_erl], eax        ; clear error line number

See Also

  • ERR
  • ERL
  • ON ERROR
  • RESUME


TRY/CATCH/FINALLY - PBXA64 Compiler Help

TRY / CATCH / FINALLY / END TRY

Structured exception handling block.

Kind: Statement | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

TRY
  [tryStatements]
CATCH [var]
  [catchStatements]
FINALLY
  [finallyStatements]
END TRY

Description

TRY/CATCH/FINALLY provides structured exception handling. Statements in the TRY block are executed normally. If an exception occurs (via THROW or a hardware exception), control transfers to the CATCH block. The optional var receives the exception code. The FINALLY block is always executed, whether or not an exception occurred, and is typically used for cleanup. The runtime uses Vectored Exception Handling (VEH) via AddVectoredExceptionHandler to intercept exceptions (including access violations, division by zero, and THROW).

Parameters

var — optional LONG variable to receive the exception code.
tryStatements — code to execute that may throw.
catchStatements — code executed if an exception occurs.
finallyStatements — code always executed after TRY/CATCH.

Parameters

Section | Description
TRY | Body of code that may generate an exception.
CATCH var | Exception handler; optional variable receives exception code.
FINALLY | Cleanup code that always runs.
END TRY | Terminates the TRY block.

Examples

TRY
  LOCAL x AS LONG
  x = 42 / 0       ' division by zero exception
CATCH code
  PRINT "Exception caught: "; code
FINALLY
  PRINT "Cleanup"
END TRY

Assembler Output

; PBXA64 x64 assembly structure for TRY/CATCH
; Uses VEH (Vectored Exception Handling)
push handler_address       ; register VEH handler
TRY_block_start:
  ; ... guarded code ...
  jmp TRY_done
CATCH_block:
  mov [rbp-8], excode      ; store exception code in var
  ; ... handler code ...
TRY_done:
FINALLY_block:
  ; ... always executed ...
  pop handler_address       ; unregister VEH handler

See Also

  • THROW
  • ON ERROR
  • ERROR


THROW - PBXA64 Compiler Help

THROW

Throws an exception that can be caught by a TRY/CATCH block.

Kind: Statement | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

THROW [code]

Description

THROW raises a structured exception that can be caught by a TRY/CATCH block. If code is provided, it specifies the exception code (a LONG value). If omitted, a default exception code is used. The runtime triggers an int 3 instruction which generates an EXCEPTION_BREAKPOINT, intercepted by the Vectored Exception Handler (VEH) installed by TRY. The VEH handler examines the context to determine if the exception originated from THROW and, if so, transfers control to the matching CATCH block.

Parameters

code — optional LONG exception code (default: 1).

Parameters

Parameter | Description
code | Exception code value (1-65535). Optional, defaults to 1.

Examples

TRY
  THROW 100        ' throw exception with code 100
CATCH code
  PRINT "Caught: "; code
END TRY

Assembler Output

; PBXA64 x64 assembly for THROW
mov [__pb_exception_code], 100  ; store exception code
int 3                           ; trigger breakpoint exception
                                ; VEH handler intercepts and
                                ; transfers to CATCH block

See Also

  • TRY/CATCH/FINALLY
  • ERROR
  • ON ERROR


ERR - PBXA64 Compiler Help

ERR

Returns the error code of the most recent runtime error.

Kind: Function | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

code = ERR

Description

ERR returns the error code (a LONG) of the most recent runtime error. If no error has occurred since the last ERRCLEAR or RESUME, ERR returns 0. Error codes are positive integers; standard PowerBASIC error codes range from 1 to 255, but user-generated errors via the ERROR statement can use any non-zero value. ERR is typically examined in a ON ERROR GOTO handler to determine the nature of the error and take appropriate action.

Return Value

A LONG containing the last error code (0 if no error).

Examples

ON ERROR GOTO Handler
OPEN "nofile.txt" FOR INPUT AS #1
Handler:
  SELECT CASE ERR
    CASE 53: PRINT "File not found"
    CASE 55: PRINT "File already open"
    CASE ELSE: PRINT "Error"; ERR
  END SELECT

Assembler Output

; PBXA64 x64 assembly for ERR
mov rax, [__pb_err]        ; load global error code
mov [rbp-8], eax           ; store result

See Also

  • ERL
  • ERRCLEAR
  • ON ERROR
  • ERROR


ERL - PBXA64 Compiler Help

ERL

Returns the line number of the most recent runtime error.

Kind: Function | Category: Error Handling

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

line = ERL

Description

ERL returns the source line number where the most recent runtime error occurred. The line number corresponds to the line number assigned by the compiler to each source statement. If no error has occurred since the last ERRCLEAR or RESUME, ERL returns 0. The line number is stored in __pb_erl by the runtime error dispatching logic. ERL is typically used in error handlers to report or log the exact location of an error.

Return Value

A LONG containing the source line number of the error (0 if no error).

Examples

ON ERROR GOTO Handler
  OPEN "data.txt" FOR INPUT AS #1
  INPUT #1, x
Handler:
  PRINT "Error"; ERR; "at line"; ERL
  RESUME NEXT

Assembler Output

; PBXA64 x64 assembly for ERL
mov rax, [__pb_erl]        ; load global error line number
mov [rbp-8], eax           ; store result

See Also

  • ERR
  • ERRCLEAR
  • ON ERROR
  • RESUME


OPEN - PBXA64 Compiler Help

OPEN

Opens a file for reading, writing, appending, or binary access.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

OPEN filename$ FOR {INPUT|OUTPUT|APPEND|BINARY|RANDOM} AS #fnum [LEN = reclen] [ENCODING {ANSI|UTF8|UTF16}]

Description

The OPEN statement opens a file identified by filename$ and associates it with a file number #fnum for subsequent I/O operations. The access mode determines the type of operations permitted. INPUT opens an existing file for reading. OUTPUT creates or overwrites a file for writing. APPEND opens or creates a file and positions at the end. BINARY opens for raw byte-level read/write. RANDOM opens for fixed-length record access (used with GET/PUT). The optional LEN clause specifies the record length for RANDOM mode (default 128 bytes). The ENCODING clause specifies text encoding for string I/O operations. The file number must be in the range 1-255 and must not already be open.

Parameters

Parameter | Description
filename$ | String expression containing the file path and name.
FOR mode | Access mode: INPUT, OUTPUT, APPEND, BINARY, or RANDOM.
AS #fnum | File number (1-255) to associate with the opened file.
LEN = reclen | Optional. Record length in bytes for RANDOM mode.
ENCODING enc | Optional. Text encoding: ANSI (default), UTF8, or UTF16.

Examples

OPEN "C:\DATA\INPUT.TXT" FOR INPUT AS #1
OPEN "OUTPUT.DAT" FOR OUTPUT AS #2
OPEN "LOG.TXT" FOR APPEND AS #3
OPEN "DATA.BIN" FOR BINARY AS #4
OPEN "RECORDS.DAT" FOR RANDOM AS #5 LEN = 256
OPEN "UNICODE.TXT" FOR INPUT AS #6 ENCODING UTF8

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for OPEN
; Pass filename string, mode, encoding to __pb_file_open
push  encoding      ; ANSI=0, UTF8=1, UTF16=2
push  mode          ; 0=INPUT, 1=OUTPUT, etc.
push  fnum
lea   rcx, filename_descrip
call  __pb_file_open
; __pb_file_open calls CreateFileA internally
; Returns handle stored in __pb_file_handles[fnum]

See Also

  • CLOSE
  • FREEFILE
  • RESET


CLOSE - PBXA64 Compiler Help

CLOSE

Closes an open file and releases its associated file number.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

CLOSE #fnum

Description

The CLOSE statement closes the file associated with file number #fnum. The handle is looked up from the runtime's internal __pb_file_handles array, then CloseHandle is called to release the operating system resource. After closing, the file number becomes available for reuse (via OPEN or FREEFILE). Any unwritten buffers are flushed automatically by the operating system. Closing an already-closed file number is safe and results in a no-op.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.

Examples

OPEN "TEST.DAT" FOR INPUT AS #1
' ... read operations ...
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for CLOSE
mov   ecx, fnum
call  __pb_file_close
; __pb_file_close looks up handle from __pb_file_handles[ecx]
; Then calls CloseHandle(handle)
; Sets __pb_file_handles[ecx] = INVALID_HANDLE_VALUE

See Also

  • OPEN
  • RESET
  • FREEFILE


RESET - PBXA64 Compiler Help

RESET

Closes all open files.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

RESET

Description

The RESET statement closes all open files (file numbers 1 through 15). The runtime iterates through the __pb_file_handles array and calls CloseHandle for each valid handle. This is equivalent to calling CLOSE for every open file. RESET is typically used during program cleanup or before performing operations that require all files to be closed. After RESET, all file numbers become available for reuse.

Parameters

Parameter | Description
None | RESET takes no parameters.

Examples

OPEN "FILE1.DAT" FOR INPUT AS #1
OPEN "FILE2.DAT" FOR OUTPUT AS #2
' ... processing ...
RESET   ' closes both files

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for RESET
call  __pb_file_reset
; __pb_file_reset loops through __pb_file_handles[1..15]
; For each valid handle: calls CloseHandle
; Sets all entries to INVALID_HANDLE_VALUE

See Also

  • CLOSE
  • OPEN


PRINT # - PBXA64 Compiler Help

PRINT #

Writes data to a file opened in text mode (sequentially).

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

PRINT #fnum, expr1, expr2, ...

Description

The PRINT # statement writes one or more expressions to a file opened in OUTPUT, APPEND, or RANDOM mode. String expressions are written directly using __pb_file_print_cstr. Numeric expressions are formatted and written using __pb_file_print_long (or the appropriate numeric variant). Items are separated by tab characters (CHR$(9)) unless a semicolon is used as a separator, which suppresses the tab. A carriage-return/linefeed pair (CHR$(13)+CHR$(10)) is appended after the last expression unless the statement ends with a semicolon.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
expr1, ... | One or more expressions to write. Strings and numeric types are supported.

Examples

OPEN "OUTPUT.TXT" FOR OUTPUT AS #1
PRINT #1, "Hello, World!"
PRINT #1, "Value:", 42, "Pi:", 3.14159
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for PRINT # (string)
mov   rcx, fnum
lea   rdx, string_descriptor
call  __pb_file_print_cstr
; Uses WriteFile internally

; For numeric values:
mov   rcx, fnum
mov   rdx, numeric_value
call  __pb_file_print_long

See Also

  • WRITE #
  • INPUT #
  • PRINT (console)


WRITE # - PBXA64 Compiler Help

WRITE #

Writes comma-delimited data to a file with strings enclosed in quotes.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

WRITE #fnum, expr1, expr2, ...

Description

The WRITE # statement writes data to a file similarly to PRINT #, but with automatic delimiter and quoting conventions. String expressions are written enclosed in double quotation marks. Numeric expressions are written without quotes. Items are automatically separated by commas. A carriage-return/linefeed pair terminates the output line. WRITE # is particularly useful for creating CSV files that can be read back with INPUT #. The output format ensures that strings containing commas, spaces, or leading/trailing whitespace are properly delimited.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
expr1, ... | One or more expressions to write. Strings are quoted.

Examples

OPEN "DATA.CSV" FOR OUTPUT AS #1
WRITE #1, "John Doe", 35, "Engineer"
WRITE #1, "Jane Smith", 28, "Designer"
CLOSE #1
' File contents:
' "John Doe",35,"Engineer"
' "Jane Smith",28,"Designer"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for WRITE #
; Each string value is quoted, values comma-separated
mov   rcx, fnum
lea   rdx, string_descriptor
call  __pb_file_write_cstr   ; writes "value"
; Commas inserted automatically between items
; CRLF after last item

See Also

  • PRINT #
  • INPUT #


INPUT # - PBXA64 Compiler Help

INPUT #

Reads comma-separated values from a file into variables.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

INPUT #fnum, var1, var2, ...

Description

The INPUT # statement reads comma-separated, type-delimited values from a text file and assigns them to the specified variables. For string variables, leading and trailing whitespace is stripped, and quoted strings (from WRITE # output) have their quotes removed. For numeric variables, the input is parsed according to the variable's type (INTEGER, LONG, QUAD, SINGLE, DOUBLE). A carriage-return/linefeed pair terminates the input line. INPUT # is the complementary read operation for data written with WRITE #. If insufficient data is available on the current line, reading continues to the next line.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
var1, ... | One or more variables to receive the parsed values.

Examples

OPEN "DATA.CSV" FOR INPUT AS #1
INPUT #1, name$, age, job$
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for INPUT #
mov   rcx, fnum
lea   rdx, string_descriptor  ; or numeric var addr
call  __pb_file_input_cstr
; Reads until comma or CRLF, parses and assigns

See Also

  • PRINT #
  • WRITE #
  • LINE INPUT #


LINE INPUT # - PBXA64 Compiler Help

LINE INPUT #

Reads an entire line from a file into a string variable.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LINE INPUT #fnum, strvar

Description

The LINE INPUT # statement reads a complete line from a text file (up to but not including the carriage-return/linefeed terminator) and stores it in the specified string variable strvar. Unlike INPUT #, LINE INPUT # does not split on commas or strip quotes — the entire line is read as-is. Reading continues character by character until a CR (CHR$(13)) or LF (CHR$(10)) is encountered, or the end of file is reached. The CR/LF is consumed but not stored in the output string. LINE INPUT # is ideal for reading text files line-by-line where the data may contain embedded commas or quotes.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
strvar | String variable to receive the line contents.

Examples

OPEN "README.TXT" FOR INPUT AS #1
DO UNTIL EOF(1)
  LINE INPUT #1, line$
  PRINT line$
LOOP
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for LINE INPUT #
mov   rcx, fnum
lea   rdx, string_descriptor
call  __pb_file_line_input
; Reads char-by-char until CR (0x0D) or LF (0x0A)
; CR/LF consumed but not included in result
; String stored via PB_STRING64 descriptor

See Also

  • INPUT #
  • PRINT #
  • EOF


GET # - PBXA64 Compiler Help

GET #

Reads binary data from a file into a variable.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

GET #fnum [, pos] , var

Description

The GET # statement reads a block of binary data from a file opened in BINARY or RANDOM mode into the specified variable var. The optional pos parameter specifies the byte position (1-based) in BINARY mode or record number in RANDOM mode at which to start reading. If omitted, reading continues from the current file position. The number of bytes read equals the size of the variable (LEN(var)). For RANDOM mode files, the record length is determined by the LEN parameter specified in the OPEN statement. GET # is the complementary operation to PUT #. The underlying runtime call __pb_file_get uses ReadFile to perform the I/O.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
pos | Optional. Byte position (BINARY) or record number (RANDOM).
var | Variable to receive the data. Size determines bytes read.

Examples

OPEN "DATA.BIN" FOR BINARY AS #1
GET #1, 1, header    ' read header at byte 1
GET #1, , record     ' read next record at current position
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for GET #
mov   rcx, fnum
mov   rdx, position    ; NULL if omitted
mov   r8,  var_addr
mov   r9,  var_size    ; LEN(var)
call  __pb_file_get
; __pb_file_get calls ReadFile internally

See Also

  • PUT #
  • SEEK
  • LOF


PUT # - PBXA64 Compiler Help

PUT #

Writes binary data from a variable to a file.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

PUT #fnum [, pos] , var

Description

The PUT # statement writes the binary contents of a variable to a file opened in BINARY or RANDOM mode. The optional pos parameter specifies the byte position (1-based) in BINARY mode or record number in RANDOM mode. If omitted, writing occurs at the current file position. The number of bytes written equals the size of the variable (LEN(var)). For RANDOM mode files, each record written has the length specified by the LEN parameter in the OPEN statement. PUT # is the complementary operation to GET #. The underlying runtime call __pb_file_put uses WriteFile to perform the I/O.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
pos | Optional. Byte position (BINARY) or record number (RANDOM).
var | Variable containing data to write.

Examples

OPEN "DATA.BIN" FOR BINARY AS #1
PUT #1, 1, header    ' write header at byte 1
PUT #1, , record     ' write next record at current position
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for PUT #
mov   rcx, fnum
mov   rdx, position    ; NULL if omitted
mov   r8,  var_addr
mov   r9,  var_size    ; LEN(var)
call  __pb_file_put
; __pb_file_put calls WriteFile internally

See Also

  • GET #
  • SEEK
  • OPEN


SEEK - PBXA64 Compiler Help

SEEK

Positions the file pointer, or returns the current position.

Kind: Statement / Function | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SEEK #fnum, pos    ' statement: set position
result& = SEEK(#fnum)  ' function: get position

Description

The SEEK statement sets the file pointer for the specified file to the given byte position (BINARY mode) or record number (RANDOM mode). Positions are 1-based, meaning position 1 is the first byte or record. The SEEK function returns the current byte position (BINARY) or record number (RANDOM) of the file pointer. The underlying implementation uses SetFilePointer with FILE_BEGIN for positioning or FILE_CURRENT for querying the current position.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.
pos | Byte position or record number (1-based).

Examples

OPEN "FILE.DAT" FOR BINARY AS #1
SEEK #1, 100         ' move to byte 100
pos& = SEEK(#1)      ' query current position
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for SEEK (statement)
mov   rcx, fnum
mov   rdx, position
call  __pb_file_seek
; Calls SetFilePointer(handle, pos, NULL, FILE_BEGIN)

; For SEEK function:
mov   rcx, fnum
call  __pb_file_seek_get
; Calls SetFilePointer(handle, 0, NULL, FILE_CURRENT)

See Also

  • GET #
  • PUT #
  • LOF
  • LOC


FLUSH - PBXA64 Compiler Help

FLUSH

Flushes file buffers to disk.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

FLUSH #fnum

Description

The FLUSH statement forces any buffered data for the specified file to be written to disk. This ensures data integrity without closing the file. FLUSH calls the Windows FlushFileBuffers API, which writes any pending data from the operating system's file cache to the storage device. FLUSH is useful for logging applications or any scenario where data must be persisted immediately. Note that FLUSH incurs a performance cost and should be used only when data durability is required.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.

Examples

OPEN "LOG.TXT" FOR APPEND AS #1
PRINT #1, "Transaction complete"
FLUSH #1        ' ensure log entry is written to disk

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for FLUSH
mov   rcx, fnum
call  __pb_file_flush
; __pb_file_flush calls FlushFileBuffers(handle)
; Returns non-zero on success, zero on failure

See Also

  • CLOSE
  • SETEOF


SETEOF - PBXA64 Compiler Help

SETEOF

Truncates a file at the current position.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SETEOF #fnum

Description

The SETEOF statement truncates the file at the current file pointer position. All data beyond the current position is discarded, and the file's end is set to the current pointer. SETEOF calls the Windows SetEndOfFile API. This is useful when writing variable-length data to a file where the final size may be smaller than the original allocation. After SETEOF, the file pointer remains at its current position. The file must be opened in BINARY or RANDOM mode for this operation.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.

Examples

OPEN "DATA.BIN" FOR BINARY AS #1
SEEK #1, 500       ' move to desired end position
SETEOF #1           ' truncate file at byte 500
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for SETEOF
mov   rcx, fnum
call  __pb_file_seteof
; __pb_file_seteof calls SetEndOfFile(handle)
; Returns non-zero on success, zero on failure

See Also

  • FLUSH
  • SEEK
  • CLOSE


LOF - PBXA64 Compiler Help

LOF

Returns the length of an open file in bytes.

Kind: Function | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = LOF(#fnum)

Description

The LOF (Length Of File) function returns the total size of an open file in bytes. The underlying implementation calls the Windows GetFileSize API, which queries the file system for the current size. LOF is valid for any open file regardless of the access mode (INPUT, OUTPUT, BINARY, RANDOM, APPEND). For a newly created or empty file, LOF returns zero. The returned value is a LONG (64-bit integer on Windows x64).

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.

Examples

OPEN "FILE.DAT" FOR BINARY AS #1
filesize& = LOF(1)
PRINT "File size:", filesize&
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for LOF
mov   rcx, fnum
call  __pb_file_lof
; Calls GetFileSize(handle, NULL)
; Returns 64-bit file size in RAX

See Also

  • EOF
  • LOC
  • SEEK


EOF - PBXA64 Compiler Help

EOF

Returns TRUE when the file pointer is at the end of a file.

Kind: Function | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = EOF(#fnum)

Description

The EOF (End Of File) function returns -1 (TRUE) if the file pointer for the specified file is at or beyond the end of the file, or 0 (FALSE) otherwise. EOF compares the current file position (obtained via SetFilePointer) with the total file size (obtained via GetFileSize). EOF is commonly used as a loop condition when reading through a file sequentially with INPUT #, LINE INPUT #, or GET # to avoid attempting to read past the end of the file. For an empty file, EOF returns -1 immediately.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.

Examples

OPEN "FILE.TXT" FOR INPUT AS #1
DO UNTIL EOF(1)
  LINE INPUT #1, line$
  PRINT line$
LOOP
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for EOF
mov   rcx, fnum
call  __pb_file_eof
; Compares current file position vs. file size
; Returns -1 (TRUE) if pos >= size, else 0 (FALSE)

See Also

  • LOF
  • LOC
  • SEEK


LOC - PBXA64 Compiler Help

LOC

Returns the current byte or record position in an open file.

Kind: Function | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = LOC(#fnum)

Description

The LOC (Location) function returns the current position of the file pointer for the specified file. For BINARY mode files, it returns the current byte position (0-based). For RANDOM mode files, it returns the current record number (1-based), calculated by dividing the current byte position by the record length. The underlying implementation calls SetFilePointer with FILE_CURRENT to obtain the current position. LOC is useful for tracking how far through a file processing has progressed.

Parameters

Parameter | Description
#fnum | File number (1-255) of an open file.

Examples

OPEN "FILE.DAT" FOR BINARY AS #1
position& = LOC(1)
PRINT "Current position:", position&
SEEK #1, 500
position& = LOC(1)
PRINT "Now at:", position&
CLOSE #1

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for LOC
mov   rcx, fnum
call  __pb_file_loc
; Calls SetFilePointer(handle, 0, NULL, FILE_CURRENT)
; Returns 64-bit position in RAX

See Also

  • LOF
  • SEEK
  • EOF


FREEFILE - PBXA64 Compiler Help

FREEFILE

Returns the next available file number.

Kind: Function | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

fnum& = FREEFILE

Description

The FREEFILE function returns the lowest available (unused) file number in the range 1-255. This is useful for avoiding file number conflicts in programs that open multiple files, especially when the specific file number is not important. FREEFILE scans the runtime's __pb_file_handles array to find the first entry with INVALID_HANDLE_VALUE. The returned file number can be used directly with the OPEN statement. FREEFILE does not reserve the file number — it only returns the next free index.

Parameters

Parameter | Description
None | FREEFILE takes no parameters.

Examples

f& = FREEFILE
OPEN "DATA.DAT" FOR INPUT AS #f&
' f now holds a valid file number

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for FREEFILE
mov   ecx, 1         ; start scan at index 1
call  __pb_file_freefile
; Returns lowest fnum with INVALID_HANDLE_VALUE
; Basic implementation: always returns 1
; If 1 is in use, scans upward

See Also

  • OPEN
  • CLOSE


KILL - PBXA64 Compiler Help

KILL

Deletes a file from the file system.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

KILL filename$

Description

The KILL statement deletes the specified file from the file system. The file is permanently removed and cannot be recovered through normal means. The filename may include a full or partial path. If the file does not exist or cannot be deleted (e.g., read-only attribute set), a runtime error is raised. The underlying implementation calls the Windows DeleteFileA API. KILL cannot delete directories — use RMDIR for that purpose.

Parameters

Parameter | Description
filename$ | String expression containing the path and name of the file to delete.

Examples

KILL "C:\DATA\OLD_FILE.TXT"
KILL "TEMP.DAT"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for KILL
lea   rcx, filename_descrip
call  __pb_file_kill
; Calls DeleteFileA(filename)
; Returns non-zero on success, zero on failure

See Also

  • NAME
  • FILECOPY
  • RMDIR


NAME - PBXA64 Compiler Help

NAME

Renames a file or moves it to a new location.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

NAME oldname$ AS newname$

Description

The NAME statement renames a file or moves it to a different directory. The source file oldname$ is renamed to newname$, which may include a different path to move the file across directories. If a file with the new name already exists, a runtime error is raised. NAME cannot rename open files or across different drives. The underlying implementation calls the Windows MoveFileA API.

Parameters

Parameter | Description
oldname$ | String expression containing the current file path and name.
AS newname$ | String expression containing the new file path and name.

Examples

NAME "OLD.TXT" AS "NEW.TXT"
NAME "C:\SRC\FILE.DAT" AS "C:\DST\FILE.DAT"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for NAME
lea   rcx, oldname_descrip
lea   rdx, newname_descrip
call  __pb_file_name
; Calls MoveFileA(oldname, newname)
; Returns non-zero on success, zero on failure

See Also

  • KILL
  • FILECOPY


FILECOPY - PBXA64 Compiler Help

FILECOPY

Copies a file from one location to another.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

FILECOPY source$, dest$

Description

The FILECOPY statement copies an existing file specified by source$ to the location specified by dest$. If the destination file already exists, it is overwritten. The copy preserves file attributes but may not preserve extended attributes or security permissions. The source and destination can include full or partial paths. The underlying implementation calls the Windows CopyFileA API.

Parameters

Parameter | Description
source$ | String expression containing the source file path and name.
dest$ | String expression containing the destination file path and name.

Examples

FILECOPY "SOURCE.DAT", "DEST.DAT"
FILECOPY "C:\DATA\BACKUP.BIN", "D:\ARCHIVE\BACKUP.BIN"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for FILECOPY
lea   rcx, source_descrip
lea   rdx, dest_descrip
call  __pb_file_copy
; Calls CopyFileA(source, dest, FALSE)
; FALSE = overwrite existing destination files

See Also

  • KILL
  • NAME


MKDIR - PBXA64 Compiler Help

MKDIR

Creates a new directory.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

MKDIR path$

Description

The MKDIR statement creates a new directory at the specified path. All intermediate directories in the path must already exist — MKDIR does not create parent directories automatically. If the directory already exists or cannot be created (e.g., invalid path, insufficient permissions), a runtime error is raised. The underlying implementation calls the Windows CreateDirectoryA API.

Parameters

Parameter | Description
path$ | String expression containing the path of the directory to create.

Examples

MKDIR "C:\DATA\NEWDIR"
MKDIR "ARCHIVE"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for MKDIR
lea   rcx, path_descrip
call  __pb_file_mkdir
; Calls CreateDirectoryA(path, NULL)
; Returns non-zero on success, zero on failure

See Also

  • CHDIR
  • RMDIR


CHDIR - PBXA64 Compiler Help

CHDIR

Changes the current working directory.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

CHDIR path$

Description

The CHDIR statement changes the current working directory of the process to the specified path$. Subsequent file operations using relative paths will be resolved relative to the new directory. If the specified path does not exist, a runtime error is raised. The underlying implementation calls the Windows SetCurrentDirectoryA API.

Parameters

Parameter | Description
path$ | String expression containing the directory path.

Examples

CHDIR "C:\DATA"
CHDIR "..\ARCHIVE"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for CHDIR
lea   rcx, path_descrip
call  __pb_file_chdir
; Calls SetCurrentDirectoryA(path)
; Returns non-zero on success, zero on failure

See Also

  • MKDIR
  • RMDIR
  • CURDIR$


RMDIR - PBXA64 Compiler Help

RMDIR

Removes an empty directory.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

RMDIR path$

Description

The RMDIR statement removes an empty directory from the file system. The directory must be empty (contain no files or subdirectories). If the directory does not exist, contains files, or cannot be removed, a runtime error is raised. The underlying implementation calls the Windows RemoveDirectoryA API. To remove a non-empty directory, files must be deleted with KILL first.

Parameters

Parameter | Description
path$ | String expression containing the path of the directory to remove.

Examples

RMDIR "C:\DATA\OLDDIR"
RMDIR "TEMP"

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for RMDIR
lea   rcx, path_descrip
call  __pb_file_rmdir
; Calls RemoveDirectoryA(path)
; Returns non-zero on success, zero on failure

See Also

  • MKDIR
  • CHDIR
  • KILL


SETATTR - PBXA64 Compiler Help

SETATTR

Sets file attributes for a specified file.

Kind: Statement | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SETATTR filename$, attrs

Description

The SETATTR statement sets the file system attributes for the specified file. The attrs parameter is a bitmask of file attribute constants such as %FILE_ATTRIBUTE_READONLY, %FILE_ATTRIBUTE_HIDDEN, %FILE_ATTRIBUTE_SYSTEM, or %FILE_ATTRIBUTE_ARCHIVE. Multiple attributes can be combined using OR. To clear attributes, pass the desired combination (excluding the attributes to remove). The underlying implementation calls the Windows SetFileAttributesA API.

Parameters

Parameter | Description
filename$ | String expression containing the file path and name.
attrs | Numeric expression containing the attribute bitmask.

Examples

SETATTR "READONLY.DAT", %FILE_ATTRIBUTE_READONLY
SETATTR "HIDDEN.DAT", %FILE_ATTRIBUTE_HIDDEN OR %FILE_ATTRIBUTE_SYSTEM

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for SETATTR
lea   rcx, filename_descrip
mov   rdx, attributes
call  __pb_file_setattr
; Calls SetFileAttributesA(filename, attributes)
; Returns non-zero on success, zero on failure

See Also

  • GETATTR
  • KILL


GETATTR - PBXA64 Compiler Help

GETATTR

Returns the file attributes of a specified file.

Kind: Function | Category: File I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = GETATTR(filename$)

Description

The GETATTR function returns the file system attributes of the specified file as a bitmask. Returned values may include %FILE_ATTRIBUTE_READONLY (1), %FILE_ATTRIBUTE_HIDDEN (2), %FILE_ATTRIBUTE_SYSTEM (4), %FILE_ATTRIBUTE_DIRECTORY (16), %FILE_ATTRIBUTE_ARCHIVE (32), and others. Common checks can be performed using AND (&) to test individual attribute bits. If the file does not exist, a runtime error is raised. The underlying implementation calls the Windows GetFileAttributesA API.

Parameters

Parameter | Description
filename$ | String expression containing the file path and name.

Examples

attr& = GETATTR("FILE.DAT")
IF attr& AND %FILE_ATTRIBUTE_READONLY THEN
  PRINT "File is read-only"
END IF

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for GETATTR
lea   rcx, filename_descrip
call  __pb_file_getattr
; Calls GetFileAttributesA(filename)
; Returns attribute bitmask in EAX

See Also

  • SETATTR
  • KILL
  • DIR$


DATA - PBXA64 Compiler Help

DATA

Stores literal data values for retrieval by the READ statement.

Kind: Statement | Category: Data / READ / RESTORE

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

DATA val1, val2, ...

Description

DATA statements hold one or more literal values separated by commas. They are non-executable and can be placed anywhere in the source. Values are retrieved sequentially by READ statements at runtime. DATA values can be numeric or string literals. Strings containing commas or leading/trailing spaces must be quoted.

Parameters

Parameter | Description
valN | A literal numeric or string value.

Examples

DATA 10, 20, 30, 40, 50
DATA "Alice", "Bob", "Charlie"
DATA 3.14, 2.78, 1.41

FOR i = 1 TO 5
    READ x
    PRINT x
NEXT

Assembler Output

The compiler generates the following x64 code for this command:

; DATA values are stored in the .rdata section:
.rdata
data_pool:
    .quad 10, 20, 30, 40, 50
    .ascii "Alice", 0
    .ascii "Bob", 0
    .ascii "Charlie", 0
    .quad 0x40091EB851EB851F  ; 3.14
    .quad 0x40063D70A3D70A3D  ; 2.78
    .quad 0x3FF693E593E593E6  ; 1.41

See Also

  • READ
  • RESTORE


READ - PBXA64 Compiler Help

READ

Reads data values from DATA statements into variables.

Kind: Statement | Category: Data / READ / RESTORE

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

READ var1 [, var2, ...]

Description

READ sequentially reads values from the internal data pointer (maintained by the runtime) into the specified variables. The data pointer advances after each read. The type of each variable must match the type of the corresponding DATA value. Use RESTORE to reset the pointer.

Parameters

Parameter | Description
varN | Variable to receive the next data value. Can be numeric or string.

Examples

DATA 100, 200, 300
DATA "apple", "banana", "cherry"

READ a, b, c     ' a=100, b=200, c=300
READ s1$, s2$, s3$  ' s1$="apple", s2$="banana", s3$="cherry"

Assembler Output

The compiler generates the following x64 code for this command:

; READ accesses the runtime data pointer stored in __pb_data_ptr:
mov  rax, [__pb_data_ptr]    ; get current pointer
mov  rcx, [rax]              ; read value
add  rax, 8                  ; advance pointer by size of value
mov  [__pb_data_ptr], rax    ; store updated pointer
mov  [var1], rcx             ; store value into variable

; For string data:
mov  rax, [__pb_data_ptr]
lea  rcx, [string_descriptor]
call __pb_str_assign         ; copy string, advance pointer

See Also

  • DATA
  • RESTORE


RESTORE - PBXA64 Compiler Help

RESTORE

Resets the internal data pointer to the beginning, or to a specific DATA label.

Kind: Statement | Category: Data / READ / RESTORE

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

RESTORE
RESTORE label

Description

RESTORE resets the internal data pointer used by READ. With no argument, the pointer resets to the first DATA statement in the program. With a label argument, the pointer resets to the first DATA statement following that program label.

Parameters

Parameter | Description
label (optional) | Label name preceding a DATA statement.

Examples

DATA 10, 20, 30
DATA 40, 50, 60

READ a, b, c       ' reads 10, 20, 30
RESTORE
READ x, y, z       ' reads 10, 20, 30 again

RESTORE moredata
READ d, e, f       ' reads 40, 50, 60
moredata:
DATA 40, 50, 60

Assembler Output

The compiler generates the following x64 code for this command:

; RESTORE — resets __pb_data_ptr:
; Without label:
lea  rax, [data_start_label]
mov  [__pb_data_ptr], rax

; With label:
lea  rax, [data_label_name]
mov  [__pb_data_ptr], rax

See Also

  • DATA
  • READ


DIM - PBXA64 Compiler Help

DIM

Declares a fixed or dynamic array variable.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

DIM array(dim1 [, dim2, ...])    ' fixed-size array
DIM array()                       ' dynamic array

Description

The DIM statement declares an array variable with optional dimension bounds. For fixed-size arrays, the dimensions are specified at declaration time and the required stack memory is allocated. For dynamic arrays, DIM with empty parentheses declares the array without allocating data storage — memory is allocated later with REDIM. Array indices are 0-based by default, or 1-based if OPTION BASE 1 is in effect. The lower and upper bounds can be specified using the TO syntax: DIM array(1 TO 10). Multi-dimensional arrays are supported with comma-separated dimensions.

Parameters

Parameter | Description
array | Array name following variable naming rules.
dim1, dim2, ... | Dimension bounds (e.g., 10 or 1 TO 10).

Examples

DIM arr1(10)            ' 11 elements: 0..10
DIM arr2(1 TO 100)       ' 100 elements: 1..100
DIM arr3(5, 10)          ' 6 x 11 = 66 elements
DIM dynArr()             ' dynamic array

Assembler Output

The compiler generates the following x64 code for this command:

; Fixed-size array: stack allocation
sub   rsp, array_size      ; allocate on stack
; Array descriptor filled with bounds info

; Dynamic array: allocate descriptor
mov   rcx, descriptor_size
call  malloc
mov   [rbp-8], rax         ; store descriptor pointer

See Also

  • REDIM
  • ERASE
  • LBOUND
  • UBOUND


REDIM - PBXA64 Compiler Help

REDIM

Resizes a dynamic array, optionally preserving existing contents.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

REDIM [PRESERVE] array(dim1 [, dim2, ...])

Description

The REDIM statement resizes a previously declared dynamic array to new dimension bounds. If the PRESERVE keyword is used, the existing data in the array is copied to the new buffer and retained (subject to truncation if the new size is smaller). Without PRESERVE, the array is reallocated and its contents are undefined. REDIM allocates a new data block using malloc, copies old data if PRESERVE is specified, frees the old block, and updates the array descriptor. Only dynamic arrays (declared DIM array() with empty parentheses) can be redimensioned.

Parameters

Parameter | Description
PRESERVE | Optional. Retains existing array data.
array | Dynamic array name.
dim1, dim2, ... | New dimension bounds.

Examples

DIM arr() AS LONG
REDIM arr(100)                ' 101 elements, contents undefined
REDIM PRESERVE arr(200)       ' 201 elements, old data preserved

Assembler Output

The compiler generates the following x64 code for this command:

; Without PRESERVE: simple realloc
mov   rcx, new_size
mov   rdx, descriptor_addr
call  __pb_redim

; With PRESERVE:
; 1. malloc new_size bytes
; 2. memcpy min(old_size, new_size) bytes
; 3. free old block
; 4. update descriptor

See Also

  • DIM
  • ERASE
  • ARRAY DELETE
  • ARRAY INSERT


ERASE - PBXA64 Compiler Help

ERASE

Frees the memory associated with a dynamic array.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ERASE array

Description

The ERASE statement frees all memory associated with a dynamic array, including the array descriptor and the data buffer. After ERASE, the array is in an uninitialized state and must be redimensioned with REDIM before further use. For fixed-size arrays, ERASE resets all elements to their default values (zero for numeric types, empty for strings) but does not free any memory. ERASE is the proper way to release array resources before the variable goes out of scope.

Parameters

Parameter | Description
array | Array variable to erase.

Examples

DIM arr() AS LONG
REDIM arr(100)
' ... use array ...
ERASE arr           ' frees memory
REDIM arr(50)        ' reallocate

Assembler Output

The compiler generates the following x64 code for this command:

; Dynamic array: free descriptor and data buffer
mov   rcx, descriptor_addr
call  __pb_erase
; Frees data buffer via free()
; Frees descriptor via free()
; Sets descriptor pointer to NULL

; Fixed-size array: zero-fill all elements
mov   rdi, array_addr
mov   rcx, element_count
xor   eax, eax
rep   stosb

See Also

  • DIM
  • REDIM
  • FREE


ARRAY ASSIGN - PBXA64 Compiler Help

ARRAY ASSIGN

Copies all elements from one array to another.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY ASSIGN dest() = source()

Description

The ARRAY ASSIGN statement copies the entire contents of the source array source() to the destination array dest(). Both arrays must have the same number of dimensions and element type. The destination array is automatically resized to match the source array's dimensions. ARRAY ASSIGN performs a deep copy — for string arrays, each string descriptor is copied, and the underlying string data is referenced (not duplicated). The operation is equivalent to DIM dest() followed by a memcpy of the data buffer.

Parameters

Parameter | Description
dest() | Destination array (must be dynamic).
source() | Source array to copy from.

Examples

DIM src(10) AS LONG
DIM dst() AS LONG
' ... fill src ...
ARRAY ASSIGN dst() = src()

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY ASSIGN
lea   rcx, dest_descriptor
lea   rdx, src_descriptor
call  __pb_array_assign
; 1. REDIM dest to match src dimensions
; 2. memcpy(dest.data, src.data, total_bytes)

See Also

  • ARRAY COPY
  • REDIM


ARRAY SORT - PBXA64 Compiler Help

ARRAY SORT

Sorts the elements of an array in ascending or descending order.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY SORT array() [COLLATE] [FROM from_idx] [TO to_idx] [DESCEND]

Description

The ARRAY SORT statement sorts the elements of a dynamic array using an efficient comparison-based sorting algorithm. By default, sorting is in ascending order. The DESCEND keyword reverses the sort order. The optional FROM and TO parameters specify a subrange of elements to sort (0-based indices). For string arrays, the COLLATE keyword enables locale-aware case-insensitive comparison. The sort is performed in-place on the array's data buffer. Numeric arrays sort by numeric value; string arrays sort lexicographically.

Parameters

Parameter | Description
array() | Array to sort.
COLLATE | Optional. Locale-aware string comparison.
FROM | Optional. Starting index for subrange sort.
TO | Optional. Ending index for subrange sort.
DESCEND | Optional. Sort in descending order.

Examples

DIM arr(100) AS LONG
' ... fill arr ...
ARRAY SORT arr()                    ' ascending
ARRAY SORT arr() DESCEND            ' descending
ARRAY SORT arr() FROM 10 TO 50      ' sort subrange
ARRAY SORT strArr() COLLATE         ' locale-aware sort

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY SORT
lea   rcx, descriptor
mov   rdx, from_idx    ; or -1 if omitted
mov   r8,  to_idx      ; or -1 if omitted
mov   r9,  flags       ; DESCEND, COLLATE bits
call  __pb_array_sort
; Uses qsort or custom comparison-based sort

See Also

  • ARRAY SCAN
  • ARRAY REVERSE


ARRAY SCAN - PBXA64 Compiler Help

ARRAY SCAN

Performs a binary search on a sorted array.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY SCAN array() [COLLATE] = value TO result

Description

The ARRAY SCAN statement performs a binary search on a sorted array to find the specified value. The array must be sorted in ascending order prior to calling ARRAY SCAN, typically via ARRAY SORT. The result variable receives the 0-based index of the found element if the value exists, or -1 if the value is not found. For string arrays, the COLLATE keyword enables locale-aware comparison. ARRAY SCAN is significantly faster than a linear search for large sorted arrays, operating in O(log n) time.

Parameters

Parameter | Description
array() | Sorted array to search.
COLLATE | Optional. Locale-aware string comparison.
value | Value to search for.
result | Variable to receive the index, or -1 if not found.

Examples

DIM arr(1000) AS LONG
' ... fill and sort arr ...
ARRAY SORT arr()
ARRAY SCAN arr() = 42 TO idx
IF idx >= 0 THEN
  PRINT "Found at index:", idx
END IF

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY SCAN
lea   rcx, descriptor
mov   rdx, value
mov   r8,  flags
call  __pb_array_scan
; Binary search on sorted array
; Returns index in RAX, or -1 if not found

See Also

  • ARRAY SORT


ARRAY REVERSE - PBXA64 Compiler Help

ARRAY REVERSE

Reverses the order of elements in an array.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY REVERSE array()

Description

The ARRAY REVERSE statement reverses the order of all elements in the array in-place. The first element becomes the last, the second becomes the second-to-last, and so on. The operation swaps elements pairwise from both ends toward the center. For string arrays, the reversal operates on the string descriptors, not the underlying string data. ARRAY REVERSE is an O(n) operation where n is the number of elements.

Parameters

Parameter | Description
array() | Array to reverse.

Examples

DIM arr(10) AS LONG
' arr = [0, 1, 2, ..., 10]
ARRAY REVERSE arr()
' arr = [10, 9, 8, ..., 0]

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY REVERSE
lea   rcx, descriptor
call  __pb_array_reverse
; Swap elements pairwise from ends
; For each pair: xchg or memcpy swap

See Also

  • ARRAY SORT
  • ARRAY COPY


ARRAY COPY - PBXA64 Compiler Help

ARRAY COPY

Copies a range of elements from one array to another.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY COPY src() TO dest()

Description

The ARRAY COPY statement copies elements from the source array src() to the destination array dest(). Unlike ARRAY ASSIGN which replaces the entire destination, ARRAY COPY can copy a subrange using optional FROM and TO parameters. The destination array must already be dimensioned and large enough to receive the copied elements. ARRAY COPY performs a memcpy of the element data. For string arrays, the string descriptors are copied but the underlying string data is referenced (shallow copy for strings).

Parameters

Parameter | Description
src() | Source array to copy from.
dest() | Destination array to copy to (must be pre-allocated).

Examples

DIM src(100) AS LONG
DIM dest(100) AS LONG
' ... fill src ...
ARRAY COPY src() TO dest()

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY COPY
lea   rcx, src_descriptor
lea   rdx, dest_descriptor
mov   r8,  from_idx
mov   r9,  to_idx
call  __pb_array_copy
; memcpy(dest.data, src.data + offset, count * element_size)

See Also

  • ARRAY ASSIGN
  • ARRAY REVERSE


ARRAY DELETE - PBXA64 Compiler Help

ARRAY DELETE

Deletes one or more elements from a dynamic array, shifting remaining elements.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY DELETE array() [, count]

Description

The ARRAY DELETE statement removes elements from the current position (or the default position if none specified) in a dynamic array. The count parameter specifies how many elements to delete (default 1). Elements after the deletion point are shifted toward the beginning of the array, and the array is not resized — the element count is updated via the array descriptor. The trailing elements become undefined until the array is next accessed or resized. The position is tracked by an internal array cursor.

Parameters

Parameter | Description
array() | Dynamic array to delete from.
count | Optional. Number of elements to delete (default 1).

Examples

DIM arr(10) AS LONG
' ... fill arr ...
ARRAY DELETE arr()        ' delete 1 element at current position
ARRAY DELETE arr(), 3     ' delete 3 elements

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY DELETE
lea   rcx, descriptor
mov   rdx, position
mov   r8,  count
call  __pb_array_delete
; memmove remaining elements leftward
; Update element count in descriptor

See Also

  • ARRAY INSERT
  • REDIM


ARRAY INSERT - PBXA64 Compiler Help

ARRAY INSERT

Inserts one or more empty elements into a dynamic array, shifting existing elements.

Kind: Statement | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ARRAY INSERT array() [, count]

Description

The ARRAY INSERT statement inserts empty elements into a dynamic array at the current position, shifting existing elements toward the end. The count parameter specifies how many elements to insert (default 1). The array is reallocated if necessary to accommodate the new elements. Inserted elements are initialized to their default values (zero for numeric types, empty for strings). The position is tracked by an internal array cursor within the descriptor.

Parameters

Parameter | Description
array() | Dynamic array to insert into.
count | Optional. Number of elements to insert (default 1).

Examples

DIM arr(10) AS LONG
' ... fill arr ...
ARRAY INSERT arr()        ' insert 1 element at current position
ARRAY INSERT arr(), 3     ' insert 3 elements

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ARRAY INSERT
lea   rcx, descriptor
mov   rdx, position
mov   r8,  count
call  __pb_array_insert
; Realloc if needed, memmove right, zero-fill new slots
; Update element count in descriptor

See Also

  • ARRAY DELETE
  • REDIM


LBOUND - PBXA64 Compiler Help

LBOUND

Returns the lower bound of an array dimension.

Kind: Function | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = LBOUND(array)
result& = LBOUND(array, dim)

Description

The LBOUND function returns the smallest valid subscript for the specified array dimension. If the dimension is omitted, the first dimension (1) is assumed. For arrays declared with the TO syntax (e.g., DIM arr(5 TO 10)), LBOUND returns the specified lower bound. For arrays without an explicit lower bound (e.g., DIM arr(10)), the return value depends on OPTION BASE — 0 by default, or 1 if OPTION BASE 1 is in effect. LBOUND is typically used with UBOUND to iterate over an array without assuming its bounds.

Parameters

Parameter | Description
array | Array variable.
dim | Optional. Dimension number (1-based, default 1).

Examples

DIM arr(5 TO 15)
PRINT LBOUND(arr)     ' prints 5
PRINT LBOUND(arr, 1)  ' prints 5

DIM arr2D(1 TO 5, 2 TO 10)
PRINT LBOUND(arr2D, 1)  ' prints 1
PRINT LBOUND(arr2D, 2)  ' prints 2

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for LBOUND
mov   rcx, descriptor_addr
mov   rdx, dimension    ; 0 if omitted (default 1)
call  __pb_lbound
; Returns lower bound from descriptor's dim_info[d].lower

See Also

  • UBOUND


UBOUND - PBXA64 Compiler Help

UBOUND

Returns the upper bound of an array dimension.

Kind: Function | Category: Array Operations

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result& = UBOUND(array)
result& = UBOUND(array, dim)

Description

The UBOUND function returns the largest valid subscript for the specified array dimension. If the dimension is omitted, the first dimension (1) is assumed. For example, DIM arr(10) declares indices 0 through 10 (by default), so UBOUND(arr) returns 10, and the array has 11 elements. For multi-dimensional arrays, UBOUND with different dimension values returns the upper bound for each dimension. For a dynamic array that has not been redimensioned, UBOUND returns -1 (error condition).

Parameters

Parameter | Description
array | Array variable.
dim | Optional. Dimension number (1-based, default 1).

Examples

DIM arr(10)
PRINT UBOUND(arr)     ' prints 10

DIM arr2D(1 TO 5, 2 TO 10)
PRINT UBOUND(arr2D, 1)  ' prints 5
PRINT UBOUND(arr2D, 2)  ' prints 10

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for UBOUND
mov   rcx, descriptor_addr
mov   rdx, dimension    ; 0 if omitted (default 1)
call  __pb_ubound
; Returns upper bound from descriptor's dim_info[d].upper

See Also

  • LBOUND
  • DIM


LOCAL - PBXA64 Compiler Help

LOCAL

Declares local variables within a SUB or FUNCTION.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LOCAL var [AS type] [, var [AS type]] ...

Description

LOCAL declares variables that are local to the current SUB or FUNCTION. Each local variable exists only while the procedure is executing and is destroyed when the procedure exits. The AS type clause specifies the data type; if omitted, the default type (typically LONG) is used. Supported types include BYTE, INTEGER, WORD, LONG, DWORD, QUAD, SINGLE, DOUBLE, STRING, WSTRING, VARIANT, and UDT types. The compiler allocates stack space for all local variables in the procedure prologue via sub rsp, frame_size. Local variables are accessed via RBP-relative offsets.

Parameters

var — variable name.
type — data type (BYTE, INTEGER, LONG, QUAD, SINGLE, DOUBLE, STRING, etc.).

Parameters

Parameter | Description
var | Variable name (follows PowerBASIC naming rules).
AS type | Optional type specifier. Defaults to LONG.

Examples

SUB MyProc()
  LOCAL x AS LONG
  LOCAL s AS STRING
  LOCAL a, b, c AS DOUBLE
  x = 42: s = "hello"
END SUB

Assembler Output

; PBXA64 x64 assembly for LOCAL (prologue)
push rbp
mov rbp, rsp
sub rsp, 64                ; allocate stack frame for locals

; Accessing local variables:
mov dword [rbp-8], 42      ; store to LOCAL LONG
lea rax, [rbp-32]          ; address of LOCAL STRING descriptor

See Also

  • GLOBAL
  • STATIC
  • SHARED
  • THREADED


GLOBAL - PBXA64 Compiler Help

GLOBAL

Declares global variables accessible from all procedures in the program.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

GLOBAL var [AS type] [, var [AS type]] ...

Description

GLOBAL declares variables that are accessible from any SUB or FUNCTION in the program. Global variables are allocated in the .data section of the PE image and exist for the lifetime of the program. They are initialized to zero unless otherwise specified. The AS type clause specifies the data type; if omitted, the default type (typically LONG) is used. Global variables should be declared at module level, outside any SUB or FUNCTION. Access to global variables uses RIP-relative addressing.

Parameters

var — variable name.
type — data type specifier.

Parameters

Parameter | Description
var | Variable name (module-level scope).
AS type | Optional type specifier. Defaults to LONG.

Examples

GLOBAL g_counter AS LONG
GLOBAL g_name AS STRING

SUB Increment()
  g_counter += 1
END SUB

Assembler Output

; PBXA64 x64 assembly for GLOBAL variable access
mov eax, [rip+g_counter]   ; load global variable
add eax, 1
mov [rip+g_counter], eax   ; store back

; .data section allocation:
; .data
; g_counter: dd 0
; g_name: times 32 db 0    ; PB_STRING64 descriptor

See Also

  • LOCAL
  • SHARED
  • STATIC
  • THREADED


STATIC - PBXA64 Compiler Help

STATIC

Declares persistent local variables that retain their values between calls.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

STATIC var [AS type] [, var [AS type]] ...

Description

STATIC declares variables that are local in scope (visible only within the current procedure) but global in lifetime (they persist between procedure calls). Unlike LOCAL variables, STATIC variables are allocated in the .data section and retain their values even after the procedure exits. They are initialized only once, before the procedure is first called, to zero (or the specified initial value). STATIC variables are useful for accumulators, counters, and caches that must persist across invocations.

Parameters

var — variable name.
type — data type specifier.

Parameters

Parameter | Description
var | Variable name (local scope, global lifetime).
AS type | Optional type specifier. Defaults to LONG.

Examples

SUB Counter()
  STATIC count AS LONG
  count = count + 1
  PRINT "Called "; count; " times"
END SUB

Assembler Output

; PBXA64 x64 assembly for STATIC variable
; Allocated in .data section, accessed via RIP-relative
mov eax, [rip+count]       ; load static value
inc eax
mov [rip+count], eax       ; store back

; .data section:
; count: dd 0               ; one-time zero initialization

See Also

  • LOCAL
  • GLOBAL
  • SHARED
  • THREADED


SHARED - PBXA64 Compiler Help

SHARED

Declares a variable that is shared between the module level and a procedure.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SHARED var [AS type]

Description

SHARED declares a variable inside a SUB or FUNCTION that refers to a module-level (GLOBAL) variable of the same name. The SHARED statement creates an alias to the global variable, allowing the procedure to access it without passing it as a parameter. If the global variable does not exist or has a different type, a compile-time error is generated. SHARED is useful for reducing parameter passing while maintaining code clarity.

Parameters

var — variable name that matches a GLOBAL declaration.
type — optional type specifier (must match global declaration).

Parameters

Parameter | Description
var | Variable name (must match a GLOBAL variable).
AS type | Type specifier (must match the GLOBAL declaration).

Examples

GLOBAL g_count AS LONG

SUB MyProc()
  SHARED g_count AS LONG
  g_count += 1        ' modifies the global g_count
END SUB

Assembler Output

; PBXA64 x64 assembly for SHARED (same as GLOBAL access)
mov eax, [rip+g_count]     ; load global via RIP-relative
inc eax
mov [rip+g_count], eax     ; store back

See Also

  • GLOBAL
  • LOCAL
  • STATIC
  • THREADED


THREADED - PBXA64 Compiler Help

THREADED

Declares a thread-local variable with independent storage per thread.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

THREADED var [AS type]

Description

THREADED declares a variable that has independent storage for each thread. Each thread accessing a THREADED variable sees its own copy; modifications by one thread do not affect the value seen by other threads. The runtime uses the Windows Thread Local Storage (TLS) API: TlsAlloc allocates a TLS index at program start, and TlsGetValue/TlsSetValue access the per-thread storage. THREADED variables must be declared at module level (outside procedures). They are initialized to zero for each new thread.

Parameters

var — thread-local variable name.
type — data type specifier.

Parameters

Parameter | Description
var | Thread-local variable name.
AS type | Type specifier (defaults to LONG).

Examples

THREADED t_local AS LONG

SUB ThreadProc()
  t_local = THREADCOUNT  ' each thread gets its own copy
END SUB

Assembler Output

; PBXA64 x64 assembly for THREADED variable access
; Read TLS index for the threaded variable
mov eax, [__pb_tls_index]  ; TLS slot index
call __imp_TlsGetValue      ; get pointer to thread-local storage
; Access variable at offset within TLS block
mov rcx, [rax+offset]      ; read thread-local value
; Store back
mov [rax+offset], rdx      ; write thread-local value

See Also

  • LOCAL
  • GLOBAL
  • STATIC
  • SHARED


CONST - PBXA64 Compiler Help

CONST

Declares a compile-time constant.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

CONST name = value
CONST name AS type = value

Description

CONST declares a named constant whose value is evaluated at compile time. The constant's value is substituted directly into the generated code wherever the name is used; no runtime memory or code is allocated for the constant itself. The optional AS type clause specifies the type of the constant; if omitted, the type is inferred from the value expression. Constants can be numeric (integer or floating-point) or string. Once declared, a constant's value cannot be changed.

Parameters

name — constant identifier.
value — compile-time expression evaluating to a constant value.
type — optional type specifier for the constant.

Parameters

Parameter | Description
name | Constant name.
value | Constant value expression.
AS type | Optional explicit type.

Examples

CONST PI = 3.14159
CONST MAX_SIZE AS LONG = 1024
CONST GREETING = "Hello"

Assembler Output

; CONST values are substituted at compile time.
; No runtime code is generated for the declaration.
; Usage becomes immediate operands:
mov eax, 1024              ; MAX_SIZE substituted directly
movsd xmm0, [rip+__const_pi] ; PI with floating-point literal

See Also

  • ENUM
  • LOCAL
  • GLOBAL


ENUM - PBXA64 Compiler Help

ENUM / END ENUM

Declares an enumerated type that defines a set of named integer constants.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ENUM name
  member [= value]
  [member [= value]]
  ...
END ENUM

Description

ENUM defines a set of named integer constants. Each member is assigned an integer value: if specified explicitly with = value, that value is used; otherwise, the value is one greater than the previous member (starting at 0 for the first member). Enumeration members are treated as compile-time constants, equivalent to CONST declarations. They are replaced with their integer values at compile time and generate no runtime code. Enumerations improve code readability and type safety.

Parameters

name — enumeration type name.
member — member identifier.
value — optional explicit integer value for the member.

Parameters

Parameter | Description
name | Enumeration type name.
member | Named constant identifier.
value | Optional integer value (default: auto-increment from 0).

Examples

ENUM Colors
  Red = 1
  Green
  Blue
END ENUM

LOCAL c AS LONG
c = Green       ' c = 2

Assembler Output

; ENUM members are replaced with constant values at compile time.
; No runtime code is generated for the ENUM declaration.
mov dword [rbp-8], 2       ; Green = 2 substituted directly

See Also

  • CONST
  • TYPE
  • UNION


TYPE/END TYPE - PBXA64 Compiler Help

TYPE / END TYPE

Defines a user-defined data type (UDT) with multiple fields.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

TYPE udtName
  fieldName [AS type]
  [fieldName [AS type]]
  ...
END TYPE

Description

TYPE defines a composite data type (user-defined type / UDT) that groups multiple fields under a single name. Each field can be of any built-in type (BYTE, INTEGER, LONG, QUAD, SINGLE, DOUBLE, STRING, WSTRING, etc.) or another UDT. Fields are laid out sequentially in memory with alignment padding to maintain type alignment requirements. The total size of the TYPE is the sum of field sizes plus padding. Fields are accessed by their offset from the base address of the UDT variable.

Parameters

udtName — user-defined type name.
fieldName — field name within the type.
type — data type of the field.

Parameters

Parameter | Description
udtName | Type name for subsequent variable declarations.
fieldName | Field identifier.
type | Field data type (built-in or another TYPE).

Examples

TYPE Person
  Name AS STRING
  Age AS LONG
  Salary AS DOUBLE
END TYPE

LOCAL p AS Person
p.Age = 30

Assembler Output

; PBXA64 x64 assembly for TYPE field access
; Person.Age is at offset 32 (after 32-byte PB_STRING64 descriptor)
mov dword [rbp-40], 30     ; p.Age = 30 at [rbp - 32 - 8]

; Field offsets:
; Name: offset 0  (32 bytes for PB_STRING64 descriptor)
; Age:  offset 32 (4 bytes)
; Salary: offset 40 (8 bytes, aligned)
; Total: 48 bytes

See Also

  • UNION
  • ENUM
  • LOCAL


UNION/END UNION - PBXA64 Compiler Help

UNION / END UNION

Declares overlapping fields at the same memory offset within a TYPE.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

UNION
  field1 [AS type1]
  field2 [AS type2]
  ...
END UNION

Description

UNION defines a set of fields that all share the same starting memory offset within a TYPE. All union fields overlap in memory; the size of the union is the size of its largest field. Writing to one union field changes the bytes seen by all other union fields. UNIONS are only valid inside a TYPE/END TYPE block. They are useful for memory-efficient data structures and for accessing the same data with different type interpretations.

Parameters

field — field name.
type — data type of the field.

Parameters

Parameter | Description
field | Field identifier (all fields share the same offset).
type | Field data type (determines the size of the field).

Examples

TYPE Variant64
  UNION
    n AS QUAD
    d AS DOUBLE
    b(7) AS BYTE
  END UNION
END TYPE

LOCAL v AS Variant64
v.d = 3.14159
PRINT v.n    ' prints raw bits of the double

Assembler Output

; PBXA64 x64 assembly for UNION field access
; All fields start at the same offset (offset 0 in Variant64)
movsd [rbp-16], xmm0      ; v.d = 3.14159
; Reading v.n reads the same bytes:
mov rax, [rbp-16]          ; load raw QUAD value

See Also

  • TYPE
  • ENUM
  • CONST


DECLARE - PBXA64 Compiler Help

DECLARE

Declares an external function or subroutine from a DLL.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

DECLARE FUNCTION name LIB "dllname" [ALIAS "alias"] (params) AS type
DECLARE SUB name LIB "dllname" [ALIAS "alias"] (params)

Description

DECLARE declares an external function imported from a Windows DLL. The LIB clause specifies the DLL name (without .dll extension). The optional ALIAS clause specifies the exported name if it differs from the declared name. Parameters follow standard PowerBASIC type conventions. The linker resolves the import by adding an entry to the Import Address Table (IAT) in the PE image. At runtime, calls to DECLAREd functions go through the IAT thunk.

Parameters

name — function/sub name as used in the code.
dllname — DLL file name (without .dll).
alias — optional exported name in the DLL.
params — parameter list with types.
type — return type (for FUNCTION).

Parameters

Parameter | Description
name | Name used in source code.
dllname | DLL name (without extension).
alias | Optional exported name (for ordinals or alternate names).

Examples

DECLARE FUNCTION MessageBox LIB "user32" ALIAS "MessageBoxA" ( _
  BYVAL hWnd AS LONG, lpText AS ASCIIZ, lpCaption AS ASCIIZ, _
  BYVAL uType AS LONG) AS LONG

LOCAL result AS LONG
result = MessageBox(0, "Hello", "Title", 0)

Assembler Output

; PBXA64 x64 assembly for DECLARE call
; Call goes through IAT (Import Address Table)
sub rsp, 40                ; shadow space
xor ecx, ecx               ; hWnd = 0
lea rdx, [msg]             ; lpText
lea r8, [caption]          ; lpCaption
xor r9d, r9d               ; uType = 0
call [rip+__imp_MessageBoxA] ; IAT thunk
mov [rbp-8], eax           ; store result

See Also

  • EXPORT
  • MODULE
  • CALL


EXPORT - PBXA64 Compiler Help

EXPORT

Exports a SUB or FUNCTION from a DLL for use by external programs.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SUB name EXPORT [ALIAS "alias"] (params)
FUNCTION name EXPORT [ALIAS "alias"] (params) AS type

Description

EXPORT makes a SUB or FUNCTION visible to external programs as a DLL export. The optional ALIAS clause specifies the exported name; if omitted, the procedure name is used. The EXPORT keyword is placed after the procedure name in the SUB or FUNCTION declaration. The linker adds the exported symbol to the DLL's export table, including the name (and optionally an ordinal). External programs can then call the exported procedure using DECLARE or LoadLibrary/GetProcAddress.

Parameters

name — procedure name (and export name, unless ALIAS is used).
alias — optional export name different from the procedure name.

Parameters

Parameter | Description
name | Procedure name in source code.
alias | Optional exported name for external callers.

Examples

SUB MyFunction EXPORT (BYVAL x AS LONG)
  PRINT "Called with: "; x
END SUB

FUNCTION Add EXPORT ALIAS "AddNumbers" (BYVAL a AS LONG, BYVAL b AS LONG) AS LONG
  FUNCTION = a + b
END FUNCTION

Assembler Output

; PBXA64 x64 assembly for EXPORT
; The linker generates export table entries.
; The function code itself is standard:
push rbp
mov rbp, rsp
sub rsp, 32
; ... function body ...
mov eax, [rbp+16]          ; return value in RAX/EAX
leave
ret

; Export table entry (generated by linker):
; MyFunction, AddNumbers -> addresses in DLL

See Also

  • DECLARE
  • MODULE
  • TYPE


MODULE - PBXA64 Compiler Help

MODULE / INTERFACE / IMPLEMENTATION

Defines a namespace/module with interface and implementation sections.

Kind: Statement | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

MODULE name
  INTERFACE
    ' declarations visible to users of the module
  END INTERFACE
  IMPLEMENTATION
    ' private declarations and procedure bodies
  END MODULE

Description

MODULE provides namespace organization for grouping related declarations and implementations. The INTERFACE section contains declarations that are visible outside the module (public API). The IMPLEMENTATION section contains private declarations and procedure bodies that are only accessible within the module. MODULE helps organize code into logical units with controlled visibility. Multiple modules can coexist in the same source file or across multiple files.

Parameters

name — module identifier.

Parameters

Parameter | Description
name | Module name for namespace organization.

Examples

MODULE MathLib
  INTERFACE
    DECLARE FUNCTION Square(BYVAL x AS DOUBLE) AS DOUBLE
  END INTERFACE
  IMPLEMENTATION
    FUNCTION Square(BYVAL x AS DOUBLE) AS DOUBLE
      FUNCTION = x * x
    END FUNCTION
  END MODULE

Assembler Output

; MODULE declarations do not generate code directly.
; Procedure bodies within the IMPLEMENTATION section
; generate standard x64 code with appropriate naming:
; _MathLib_Square:
;   push rbp
;   mov rbp, rsp
;   mulsd xmm0, xmm0       ; x * x
;   leave
;   ret

See Also

  • DECLARE
  • EXPORT
  • TYPE


INTERFACE - PBXA64 Compiler Help

INTERFACE / END INTERFACE

Declares a COM interface (VTable layout) for object-oriented programming.

Kind: Construct | Category: Object / COM

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

INTERFACE name [AS IUnknown | AS IDispatch]
  METHOD MethodName1 (params) AS returnType
  METHOD MethodName2 (params) AS returnType
END INTERFACE

Description

INTERFACE defines a COM-compatible vtable layout. Each METHOD declaration adds an entry to the vtable. The interface inherits from IUnknown (AddRef, Release, QueryInterface) by default, or from IDispatch if specified. INTERFACE is a compile-time construct — no code is generated at the declaration site. The vtable is emitted in the .rdata section as an array of function pointers. CLASS types can implement interfaces via the IMPLEMENTS keyword.

Examples

INTERFACE IMyInterface AS IUnknown
  METHOD DoSomething (BYVAL x AS LONG) AS LONG
END INTERFACE

Assembler Output

; VTable generated in .rdata section
; .rdata
; IMyInterface_VTable:
;   dq IUnknown_QueryInterface
;   dq IUnknown_AddRef
;   dq IUnknown_Release
;   dq IMyInterface_DoSomething

See Also

  • CLASS
  • MODULE
  • Back to command index


BYTE - PBXA64 Compiler Help

BYTE

1-byte unsigned integer data type (range 0 to 255).

Kind: Data Type | Category: Integer Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS BYTE
var = 200                ' valid range 0-255

Description

BYTE is the smallest unsigned integer type, occupying 1 byte of storage. Range: 0 to 255. No suffix character is used for BYTE literals. Arithmetic on BYTE values promotes to INTEGER (WORD) before evaluation. BYTE maps to the x86-64 AL/BL/CL/DL 8-bit registers when used in register operations.

Examples

DIM b AS BYTE
b = 42
b = b + 1               ' b = 43

Assembler Output

; BYTE variable load/store
 mov al, byte ptr [rbp-1]  ; load BYTE
 add al, 1                 ; arithmetic (promoted to WORD)
 mov byte ptr [rbp-1], al  ; store BYTE

See Also

  • WORD
  • DWORD
  • INTEGER
  • LONG
  • QUAD
  • Back to command index


WORD - PBXA64 Compiler Help

WORD

2-byte unsigned integer data type (range 0 to 65535).

Kind: Data Type | Category: Integer Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS WORD
var = 50000              ' valid range 0-65535

Description

WORD is a 2-byte unsigned integer. Range: 0 to 65535. No suffix character is used for WORD literals. WORD is equivalent to UINT16 in C. Operations on WORD values promote to LONG (32-bit signed) for intermediate calculations. WORD maps to the x86-64 AX/BX/CX/DX 16-bit registers.

Examples

DIM w AS WORD
w = 65000
w = w + 100              ' w = 65100

Assembler Output

; WORD variable load/store
 mov ax, word ptr [rbp-2]   ; load WORD (16-bit)
 add ax, 100                ; 16-bit addition
 mov word ptr [rbp-2], ax   ; store WORD

See Also

  • BYTE
  • DWORD
  • INTEGER
  • LONG
  • Back to command index


INTEGER - PBXA64 Compiler Help

INTEGER

2-byte signed integer data type (range -32768 to 32767).

Kind: Data Type | Category: Integer Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS INTEGER
var = -100               ' valid range -32768 to 32767

Description

INTEGER is a 2-byte signed integer type. The suffix character % denotes an INTEGER literal (e.g. 42%). Range: -32768 to 32767. Equivalent to INT16 in C. Values are sign-extended when promoted to LONG or QUAD. INTEGER maps to x86-64 16-bit registers and uses movsx for sign extension to wider types.

Examples

DIM i AS INTEGER
i = 100%
i = i - 200%              ' i = -100

Assembler Output

; INTEGER variable load/store
 movsx eax, word ptr [rbp-2]  ; load and sign-extend to 32-bit
 add eax, -200
 mov word ptr [rbp-2], ax     ; store back as 16-bit

See Also

  • LONG
  • WORD
  • BYTE
  • Back to command index


DWORD - PBXA64 Compiler Help

DWORD

4-byte unsigned integer data type (range 0 to 4294967295).

Kind: Data Type | Category: Integer Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS DWORD
var = 4000000000          ' valid range 0-4294967295

Description

DWORD is a 4-byte unsigned integer type. No suffix character is used for DWORD literals. Range: 0 to 4294967295. Equivalent to UINT32 in C. DWORD is the natural register width for x86-64 32-bit operations (r32 registers). This is often the most efficient type for unsigned values that fit within 32 bits. Arithmetic on DWORD values uses 32-bit register operations with zero-extension to 64-bit.

Examples

DIM dw AS DWORD
dw = 3000000000
dw = dw + 1               ' dw = 3000000001

Assembler Output

; DWORD variable load/store
 mov eax, dword ptr [rbp-4]   ; load DWORD (32-bit, zero-extends to RAX)
 inc eax
 mov dword ptr [rbp-4], eax   ; store DWORD

See Also

  • BYTE
  • WORD
  • LONG
  • QUAD
  • Back to command index


LONG - PBXA64 Compiler Help

LONG

4-byte signed integer data type (range -2^31 to 2^31-1).

Kind: Data Type | Category: Integer Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS LONG
var = -100000             ' valid range -2^31 to 2^31-1

Description

LONG is a 4-byte signed integer type. The suffix character & denotes a LONG literal (e.g. 42&). Range: -2,147,483,648 to 2,147,483,647. Equivalent to INT32 in C. LONG is the default integer type for most operations in PBXA64. Values are sign-extended when promoted to QUAD. LONG uses x86-64 32-bit register operations with sign extension (movsxd) when converting to 64-bit.

Examples

DIM l AS LONG
l = 1000&
l = l * 2                 ' l = 2000

Assembler Output

; LONG variable load/store
 mov eax, dword ptr [rbp-4]   ; load LONG (32-bit, zero-extends)
 add eax, edx
 mov dword ptr [rbp-4], eax   ; store LONG

See Also

  • INTEGER
  • QUAD
  • DWORD
  • Back to command index


QUAD - PBXA64 Compiler Help

QUAD

8-byte signed integer data type (range -2^63 to 2^63-1).

Kind: Data Type | Category: Integer Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS QUAD
DIM var AS INTEGER64       ' equivalent
var = 50000000000

Description

QUAD is an 8-byte signed integer type. The suffix && denotes a QUAD literal (e.g. 42&&). Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807. Equivalent to INT64 in C. QUAD is the native x86-64 register width — all 64-bit operations use the full RAX/RBX/RCX/RDX register set. QUAD is also known as INTEGER64 in some PBXA64 documentation.

Examples

DIM q AS QUAD
q = 50000000000&&
q = q * 1000              ' q = 50000000000000

Assembler Output

; QUAD variable load/store
 mov rax, qword ptr [rbp-8]   ; load QUAD (64-bit)
 imul rax, 1000
 mov qword ptr [rbp-8], rax   ; store QUAD

See Also

  • LONG
  • DOUBLE
  • DWORD
  • Back to command index


SINGLE - PBXA64 Compiler Help

SINGLE

4-byte IEEE 754 single-precision floating-point data type.

Kind: Data Type | Category: Floating-Point Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS SINGLE
var = 3.14                ' single-precision float

Description

SINGLE is a 4-byte IEEE 754 single-precision floating-point type. The suffix ! denotes a SINGLE literal (e.g. 3.14!). Range: approximately ±1.5 x 10^-45 to ±3.4 x 10^38, with approximately 7 significant digits of precision. SINGLE values are stored in XMM registers as scalar values. Conversions to/from integer types use cvtsi2ss and cvtss2si. The compiler uses movss for memory operations.

Examples

DIM s AS SINGLE
s = 3.14159!
s = s * 2.0               ' s = 6.28318

Assembler Output

; SINGLE variable load/store
 movss xmm0, dword ptr [rbp-4]  ; load SINGLE (32-bit float)
 mulss xmm0, xmm1               ; multiply
 movss dword ptr [rbp-4], xmm0  ; store SINGLE

See Also

  • DOUBLE
  • CSNG
  • CDBL
  • Back to command index


DOUBLE - PBXA64 Compiler Help

DOUBLE

8-byte IEEE 754 double-precision floating-point data type.

Kind: Data Type | Category: Floating-Point Types

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIM var AS DOUBLE
var = 3.14159265358979    ' double-precision float

Description

DOUBLE is an 8-byte IEEE 754 double-precision floating-point type. The suffix # denotes a DOUBLE literal (e.g. 3.14#). Range: approximately ±5.0 x 10^-324 to ±1.7 x 10^308, with approximately 15 significant digits of precision. DOUBLE values are stored in XMM registers as scalar 64-bit values. Conversions use cvtsi2sd (integer to DOUBLE), cvtsd2si (DOUBLE to integer), and cvtss2sd/cvtsd2ss for inter-float conversion. Memory operations use movsd.

Examples

DIM d AS DOUBLE
d = 3.14159265358979#
d = d * 2.0               ' d = 6.28318530717959

Assembler Output

; DOUBLE variable load/store
 movsd xmm0, qword ptr [rbp-8]  ; load DOUBLE (64-bit float)
 mulsd xmm0, xmm1               ; multiply
 movsd qword ptr [rbp-8], xmm0  ; store DOUBLE

See Also

  • SINGLE
  • CDBL
  • CSNG
  • QUAD
  • Back to command index


STRING - PBXA64 Compiler Help

STRING (Data Type)

Variable-length ANSI string using the PB_STRING64 descriptor.

Kind: Data Type | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LOCAL s AS STRING
s = "text"
s = s + "more"

Description

The STRING type represents a variable-length ANSI string. It is implemented as a PB_STRING64 descriptor structure occupying 32 bytes in memory. The descriptor layout is: data_ptr (8 bytes) — pointer to heap-allocated character buffer; len (8 bytes) — current string length in bytes (not counting null terminator); cap (8 bytes) — allocated capacity of the character buffer; flags (4 bytes) — status flags (static, dynamic, etc.); padding (4 bytes) — alignment padding. The string data is null-terminated for compatibility with C APIs, but the len field is authoritative for the string length.

Parameters

Field | Offset | Size | Description
data_ptr | 0 | 8 | Pointer to character buffer
len | 8 | 8 | Current string length
cap | 16 | 8 | Allocated buffer capacity
flags | 24 | 4 | Status flags
padding | 28 | 4 | Alignment to 32 bytes

Examples

LOCAL s AS STRING
s = "Hello, World!"
PRINT s, LEN(s)      ' prints: Hello, World! 13

Assembler Output

; PBXA64 x64 assembly for STRING access
; Load data pointer:
mov rax, [rbp-32]          ; load PB_STRING64 descriptor address
mov rax, [rax]             ; read data_ptr from descriptor
; Load length:
mov rcx, [rbp-32]
mov rcx, [rcx+8]           ; read len field
; CALL __pb_print_cstr(rbp-32) prints the string

See Also

  • WSTRING
  • VARIANT
  • LEN
  • STRPTR


WSTRING - PBXA64 Compiler Help

WSTRING (Data Type)

Variable-length wide (UTF-16) string descriptor.

Kind: Data Type | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LOCAL ws AS WSTRING
ws = "wide text"

Description

The WSTRING type represents a variable-length wide (UTF-16) string. Like STRING, it uses a 32-byte descriptor structure. The descriptor layout mirrors PB_STRING64: data_ptr (8 bytes) — pointer to heap-allocated UTF-16 buffer; len (8 bytes) — current string length in characters; cap (8 bytes) — allocated capacity in characters; flags (4 bytes) — status flags; padding (4 bytes). Each UTF-16 character occupies 2 bytes. WSTRING is used for Unicode APIs and COM BSTR interop.

Parameters

Field | Offset | Size | Description
data_ptr | 0 | 8 | Pointer to UTF-16 character buffer
len | 8 | 8 | Length in characters
cap | 16 | 8 | Capacity in characters
flags | 24 | 4 | Status flags
padding | 28 | 4 | Alignment to 32 bytes

Examples

LOCAL ws AS WSTRING
ws = "Hello, Unicode!"
PRINT ws, LEN(ws)     ' character count, not byte count

Assembler Output

; PBXA64 x64 assembly for WSTRING access
; Load data pointer (same layout as STRING):
mov rax, [rbp-32]          ; load descriptor address
mov rax, [rax]             ; read data_ptr (UTF-16 buffer)
; Load character length:
mov rcx, [rbp-32]
mov rcx, [rcx+8]           ; read len (in characters)

See Also

  • STRING
  • VARIANT
  • LEN


VARIANT - PBXA64 Compiler Help

VARIANT (Data Type)

COM VARIANT type that can hold values of any data type.

Kind: Data Type | Category: Declarations / Data Types

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LOCAL v AS VARIANT
v = 42
v = "text"
v = 3.14159

Description

The VARIANT type is a 16-byte COM VARIANT structure that can hold values of different types. It contains a type tag (VARTYPE, 2 bytes) indicating the data type stored, along with padding and a value field that can contain integers, floating-point numbers, string references, or object pointers. The PBXA64 runtime handles conversion between VARIANT and native types automatically on assignment. VARIANT supports VT_I4, VT_R8, VT_BSTR, VT_DATE, VT_BOOL, VT_DISPATCH, VT_UNKNOWN, and other COM types.

Parameters

Field | Offset | Size | Description
vt | 0 | 2 | VARTYPE tag (VT_EMPTY=0, VT_I4=3, VT_R8=5, VT_BSTR=8, etc.)
reserved | 2 | 6 | Padding/reserved
value | 8 | 8 | Value field (int64, double, or pointer)

Examples

LOCAL v AS VARIANT
v = 100             ' VT_I4
PRINT v
v = "Hello"         ' VT_BSTR
PRINT v
v = 3.14            ' VT_R8
PRINT v

Assembler Output

; PBXA64 x64 assembly for VARIANT assignment
; Assigning integer (VT_I4):
mov word [rbp-16], 3       ; vt = VT_I4
mov dword [rbp-8], 100     ; lVal = 100

; Assigning double (VT_R8):
mov word [rbp-16], 5       ; vt = VT_R8
movsd [rbp-8], xmm0        ; dblVal = 3.14

See Also

  • STRING
  • WSTRING
  • TYPE


ALLOCATE - PBXA64 Compiler Help

ALLOCATE

Allocates a block of heap memory.

Kind: Statement | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

ALLOCATE size TO pointer

Description

The ALLOCATE statement allocates a block of memory of the specified size bytes from the process heap and stores the address in pointer. The allocated memory is not initialized; its contents are undefined. If allocation fails (out of memory), a runtime error is raised. The pointer should be of type LONG (64-bit pointer) to hold the address. Memory allocated with ALLOCATE must be freed with the FREE statement when no longer needed to avoid memory leaks.

Parameters

Parameter | Description
size | Numeric expression specifying the number of bytes to allocate.
TO pointer | Variable (typically LONG) to receive the memory address.

Examples

LOCAL p AS LONG
ALLOCATE 1024 TO p           ' allocate 1024 bytes
' ... use memory at p ...
FREE p                       ' free when done

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for ALLOCATE
mov   rcx, size
call  malloc
mov   [pointer_addr], rax    ; store returned address

See Also

  • CALLOC
  • REALLOCATE
  • FREE


CALLOC - PBXA64 Compiler Help

CALLOC

Allocates and zero-initializes a block of heap memory.

Kind: Statement | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

CALLOC count, size TO pointer

Description

The CALLOC statement allocates memory for an array of count elements, each of size bytes, and initializes all bytes to zero. The total allocation is count * size bytes. The address of the allocated memory is stored in pointer. Unlike ALLOCATE, CALLOC guarantees that all memory is initialized to zero, making it suitable for allocating arrays of numeric data or structures that should start in a known state. If allocation fails, a runtime error is raised.

Parameters

Parameter | Description
count | Number of elements to allocate.
size | Size of each element in bytes.
TO pointer | Variable to receive the memory address.

Examples

LOCAL p AS LONG
CALLOC 256, 4 TO p     ' allocate 256 LONGs, zero-initialized
' ... use memory at p ...
FREE p

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for CALLOC
mov   rcx, count
mov   rdx, size
call  __pb_calloc
; Calls malloc(total) then memset(ptr, 0, total)
mov   [pointer_addr], rax

See Also

  • ALLOCATE
  • FREE


REALLOCATE - PBXA64 Compiler Help

REALLOCATE

Resizes a previously allocated block of heap memory.

Kind: Statement | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

REALLOCATE new_size TO pointer

Description

The REALLOCATE statement resizes a memory block previously allocated with ALLOCATE, CALLOC, or REALLOCATE to the specified new_size bytes. The contents of the memory block are preserved up to the minimum of the old and new sizes. If the new size is larger, the additional memory is not initialized. The pointer variable is updated with the new address, which may differ from the original if the block needed to be moved. If reallocation fails, the original block is left intact and a runtime error is raised.

Parameters

Parameter | Description
new_size | New size in bytes for the memory block.
TO pointer | Variable containing the current pointer; updated on success.

Examples

LOCAL p AS LONG
ALLOCATE 1024 TO p
REALLOCATE 2048 TO p    ' resize to 2048 bytes, data preserved
FREE p

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for REALLOCATE
mov   rcx, current_pointer
mov   rdx, new_size
call  realloc
mov   [pointer_addr], rax    ; update pointer (may differ)

See Also

  • ALLOCATE
  • CALLOC
  • FREE


FREE - PBXA64 Compiler Help

FREE

Frees a block of heap memory previously allocated with ALLOCATE or CALLOC.

Kind: Statement | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

FREE pointer

Description

The FREE statement releases a block of heap memory that was previously allocated with ALLOCATE, CALLOC, or REALLOCATE. The pointer variable retains its previous value after FREE; it is good practice to set the pointer to zero after freeing to avoid dangling pointer references. Freeing a NULL pointer (zero) is a safe no-op. Double-freeing the same pointer is undefined behavior and should be avoided. Memory leaks occur when allocated memory is not freed before the pointer goes out of scope or is overwritten.

Parameters

Parameter | Description
pointer | Variable containing the address of the memory block to free.

Examples

LOCAL p AS LONG
ALLOCATE 1024 TO p
' ... use memory ...
FREE p
p = 0      ' avoid dangling pointer

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for FREE
mov   rcx, [pointer_addr]
call  free
; If pointer is NULL (0), free() is a no-op

See Also

  • ALLOCATE
  • CALLOC
  • REALLOCATE


PEEK - PBXA64 Compiler Help

PEEK

Reads a value from a memory address.

Kind: Function | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

result = PEEK(addr)
result = PEEK(addr, type)

Description

The PEEK function reads a value from the specified memory address. With only one argument, PEEK returns a BYTE value (8-bit unsigned). With the optional type parameter, the return type can be specified: %PEEK_BYTE (1), %PEEK_WORD (2), %PEEK_INTEGER (3), %PEEK_LONG (4), %PEEK_QUAD (5), %PEEK_SINGLE (6), %PEEK_DOUBLE (7). The function performs an aligned or unaligned read of the specified size from the given address. PEEK is used for low-level memory inspection, reading hardware registers, or examining data structures.

Parameters

Parameter | Description
addr | Memory address to read from (LONG pointer).
type | Optional. Data type constant specifying read size and interpretation.

Examples

LOCAL p AS LONG
LOCAL b AS BYTE
LOCAL w AS WORD
LOCAL l AS LONG
b = PEEK(p)           ' read 1 byte
w = PEEK(p, 2)        ' read 1 word (2 bytes)
l = PEEK(p, 4)        ' read 1 LONG (4 bytes)

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for PEEK (BYTE)
mov   rcx, [addr]
movzx rax, BYTE PTR [rcx]    ; zero-extend byte

; PEEK (LONG)
mov   rcx, [addr]
mov   eax, DWORD PTR [rcx]   ; read 32-bit value

; PEEK (DOUBLE)
mov   rcx, [addr]
movq  xmm0, QWORD PTR [rcx]  ; read 64-bit as double

See Also

  • POKE
  • VARPTR
  • STRPTR


POKE - PBXA64 Compiler Help

POKE

Writes a value to a memory address.

Kind: Statement | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

POKE addr, value

Description

The POKE statement writes a value to the specified memory address. The size of the write is determined by the type of value: BYTE writes 1 byte, WORD writes 2 bytes, LONG writes 4 bytes, QUAD writes 8 bytes. For literal values without a specific type, the size is inferred from the value range. POKE does not perform any bounds checking — writing to invalid memory addresses will cause an access violation. POKE is the complementary operation to PEEK and is used for low-level memory manipulation.

Parameters

Parameter | Description
addr | Memory address to write to (LONG pointer).
value | Value to write. Type determines write size.

Examples

LOCAL p AS LONG
POKE p, 42              ' write 1 byte (value range)
POKE p, &h12345678      ' write 4 bytes (LONG range)

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for POKE (BYTE)
mov   rcx, [addr]
mov   al, byte_value
mov   BYTE PTR [rcx], al

; POKE (LONG)
mov   rcx, [addr]
mov   eax, long_value
mov   DWORD PTR [rcx], eax

; POKE (QUAD)
mov   rcx, [addr]
mov   rax, quad_value
mov   QWORD PTR [rcx], rax

See Also

  • PEEK
  • VARPTR
  • ALLOCATE


CODEPTR - PBXA64 Compiler Help

CODEPTR

Returns the memory address of a function or subroutine.

Kind: Function | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

p& = CODEPTR(procname)

Description

The CODEPTR function returns the 64-bit memory address of the entry point of a function or subroutine. The returned address can be used with CALL DWORD to invoke the procedure indirectly. CODEPTR is useful for implementing function tables, callbacks, or dynamic dispatch. The address points to the compiled x64 code of the specified procedure. CODEPTR differs from FUNCPTR primarily in that FUNCPTR is a statement form while CODEPTR is a function that can be used in expressions.

Parameters

Parameter | Description
procname | Name of a function, subroutine, or label defined in the current scope.

Examples

SUB MyProc()
  PRINT "Hello"
END SUB

p& = CODEPTR(MyProc)
CALL DWORD p& USING MyProc()   ' indirect call

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for CODEPTR
lea   rax, [proc_label]   ; load address of procedure
mov   [result_addr], rax

See Also

  • FUNCPTR
  • VARPTR
  • CALL


FUNCPTR - PBXA64 Compiler Help

FUNCPTR

Returns the memory address of a function or subroutine (statement form).

Kind: Statement | Category: Memory / Pointer

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

FUNCPTR procname TO pointer

Description

The FUNCPTR statement stores the memory address of a function or subroutine's entry point into the specified pointer variable. This is the statement form of CODEPTR. The address points to the first instruction of the compiled x64 code for the procedure. The pointer can later be used with CALL DWORD or through callback mechanisms that require a function address. FUNCPTR is useful for creating arrays of function pointers, implementing state machines, or passing callbacks to API functions.

Parameters

Parameter | Description
procname | Name of a function, subroutine, or label.
TO pointer | Variable (LONG) to receive the address.

Examples

SUB MyFunc()
  ' ...
END SUB

LOCAL p AS LONG
FUNCPTR MyFunc TO p
CALL DWORD p USING MyFunc()

Assembler Output

The compiler generates the following x64 code for this command:

; PBXA64 x64 assembly for FUNCPTR
lea   rax, [proc_label]
mov   [pointer_addr], rax

See Also

  • CODEPTR
  • VARPTR
  • CALL


PRINT - PBXA64 Compiler Help

PRINT

Outputs expressions to the console or a file.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

PRINT expr1, expr2, ...
PRINT expr1; expr2; ...
PRINT #file, expr1, ...

Description

PRINT writes text to the console (standard output) or to an open file. Commas (,) separate expressions with tab stops (14-character intervals). Semicolons (;) concatenate expressions without spacing. If no file number is specified with #file, output goes to the console via WriteFile on GetStdHandle(STD_OUTPUT_HANDLE). Numeric expressions are converted to string representation before output. PRINT automatically appends a CRLF (carriage return + line feed) unless the statement ends with a semicolon or comma.

Parameters

expr — one or more expressions (numeric or string) to print.
#file — optional file number opened with OPEN.

Parameters

Parameter | Description
expr | Expression(s) to output. Numeric values are formatted as strings automatically.
#file | Optional file number (prefixed with #) for redirected output.

Examples

PRINT "Hello, World!"
PRINT "The answer is "; 42
PRINT "Column1", "Column2", "Column3"
PRINT #1, "Written to file #1"

Assembler Output

; PBXA64 x64 assembly for PRINT numeric
mov rcx, [rbp-8]         ; pass integer value in RCX
call __pb_print_long       ; prints number to stdout

; PBXA64 x64 assembly for PRINT string
lea rcx, [rbp-32]         ; pass PB_STRING64 descriptor pointer
call __pb_print_cstr       ; prints string to stdout

See Also

  • WRITE
  • INPUT
  • OPEN


INPUT - PBXA64 Compiler Help

INPUT

Reads values from the console into variables.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

INPUT [prompt$;] var1, var2, ...
INPUT "prompt$", var1, var2, ...

Description

INPUT reads a line from the console (standard input) and parses it into the specified variables. If a prompt string is provided, it is displayed before reading. The input line is split by commas or whitespace into tokens, which are then converted to the types of the target variables. String variables read everything between delimiters. Numeric variables accept decimal format with optional sign. INPUT reads from stdin via ReadFile on GetStdHandle(STD_INPUT_HANDLE). A question mark (?) is automatically appended to the prompt if one is given.

Parameters

prompt$ — optional string prompt displayed to the user.
var — one or more variables (numeric or string) to receive input values.

Parameters

Parameter | Description
prompt$ | Optional prompt string. Trailing semicolon suppresses newline.
var | Variable(s) to receive the parsed input values.

Examples

INPUT "Enter your name: ", name$
INPUT "Age: ", age
INPUT a, b, c

Assembler Output

; PBXA64 x64 assembly for INPUT
lea rcx, [rbp-8]          ; address of prompt string descriptor
lea rdx, [rbp-32]         ; address of target variable
call __pb_input_read       ; reads and parses input

See Also

  • LINE INPUT
  • PRINT
  • OPEN


LINE INPUT - PBXA64 Compiler Help

LINE INPUT

Reads an entire line from the console into a string variable.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LINE INPUT [prompt$;] strvar

Description

LINE INPUT reads a complete line of text from the console (standard input) into a string variable. Unlike INPUT, LINE INPUT does not split the input by delimiters; it reads everything up to the terminating carriage return (CR, ASCII 13) or line feed (LF, ASCII 10). The terminating CR/LF is not included in the resulting string. A prompt string may be displayed before reading. The runtime helper reads character-by-character from stdin until CR is encountered, then stores the accumulated characters as a PB_STRING64.

Parameters

prompt$ — optional string prompt displayed before input.
strvar — string variable that receives the input line.

Parameters

Parameter | Description
prompt$ | Optional prompt string.
strvar | String variable to receive the full input line.

Examples

LINE INPUT "Enter text: ", buffer$
LINE INPUT "Address: ", address$
IF buffer$ = "" THEN PRINT "Empty line"

Assembler Output

; PBXA64 x64 assembly for LINE INPUT
lea rcx, [rbp-8]          ; prompt string descriptor address
lea rdx, [rbp-32]         ; target string variable address
call __pb_line_input       ; read entire line

; Internal: reads char-by-char until CR (0x0D)
; then builds PB_STRING64 descriptor in target

See Also

  • INPUT
  • PRINT
  • LEN


LOCATE - PBXA64 Compiler Help

LOCATE

Moves the console cursor to a specified row and column position.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LOCATE row, col

Description

LOCATE positions the text cursor in the console window at the specified row (1-based) and column (1-based). The underlying Windows API call is SetConsoleCursorPosition with a COORD structure derived from row-1 and col-1. If the specified position is outside the current console buffer dimensions, the behavior is undefined. Row 1 is the top of the screen; column 1 is the leftmost position.

Parameters

row — 1-based row number (Y coordinate).
col — 1-based column number (X coordinate).

Parameters

Parameter | Description
row | 1-based row (Y) position. Must be >= 1.
col | 1-based column (X) position. Must be >= 1.

Examples

LOCATE 10, 1     ' move to beginning of line 10
LOCATE 1, 1      ' home position (top-left)
LOCATE 12, 40    ' center of 80-column screen

Assembler Output

; PBXA64 x64 assembly for LOCATE
mov rcx, [rbp-8]          ; row (1-based)
mov rdx, [rbp-16]         ; col (1-based)
call __pb_locate           ; converts to COORD and calls SetConsoleCursorPosition

See Also

  • CLS
  • COLOR
  • WIDTH


CLS - PBXA64 Compiler Help

CLS

Clears the console screen and homes the cursor.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

CLS

Description

CLS clears the entire console screen buffer by filling all character cells with spaces (ASCII 32) and resetting the cursor position to the home position (1, 1). The runtime helper uses FillConsoleOutputCharacterA to fill the buffer with spaces and FillConsoleOutputAttribute to reset color attributes to the current console default. The total number of cells cleared is the product of the console screen buffer dimensions (columns x rows).

Examples

CLS
LOCATE 5, 10: PRINT "CLEARED"

Assembler Output

; PBXA64 x64 assembly for CLS
call __pb_cls              ; clears screen and resets cursor

; Internal: GetStdHandle(STD_OUTPUT_HANDLE)
; GetConsoleScreenBufferInfo -> dwSize
; FillConsoleOutputCharacterA(handle, ' ', nChars, coord, &bytes)
; FillConsoleOutputAttribute(handle, attr, nChars, coord, &bytes)
; SetConsoleCursorPosition(handle, (0,0))

See Also

  • LOCATE
  • COLOR
  • WIDTH


COLOR - PBXA64 Compiler Help

COLOR

Sets the foreground and background text colors for the console.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

COLOR fg [, bg]

Description

COLOR sets the console text attributes using the standard Windows console color values. fg specifies the foreground (text) color and bg specifies the background color. Both are numeric values (0-15) corresponding to the standard VGA color palette: 0=Black, 1=Blue, 2=Green, 3=Cyan, 4=Red, 5=Magenta, 6=Brown/Yellow, 7=White, 8=Gray, 9=Light Blue, 10=Light Green, 11=Light Cyan, 12=Light Red, 13=Light Magenta, 14=Yellow, 15=Bright White. The runtime helper combines fg + (bg * 16) and calls SetConsoleTextAttribute.

Parameters

fg — foreground color (0-15).
bg — optional background color (0-15); defaults to 0 (Black).

Parameters

Parameter | Description
fg | Foreground color (0-15).
bg | Background color (0-15). Defaults to 0.

Examples

COLOR 14, 1    ' Yellow on Blue
COLOR 10       ' Light Green on Black
COLOR 7, 0     ' White on Black (default)

Assembler Output

; PBXA64 x64 assembly for COLOR
mov rcx, [rbp-8]          ; foreground color
mov rdx, [rbp-16]         ; background color
call __pb_color            ; calls SetConsoleTextAttribute

See Also

  • CLS
  • LOCATE
  • WIDTH


WIDTH - PBXA64 Compiler Help

WIDTH

Sets the console screen buffer width.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

WIDTH columns

Description

WIDTH sets the width (number of columns) of the console screen buffer. The runtime helper calls SetConsoleScreenBufferSize with the specified column count and the current console window height. The minimum width is typically 16 and the maximum is 9999, though the actual range depends on the console window dimensions. The buffer height is unchanged. Changing the buffer width also affects the visible console window width.

Parameters

columns — number of columns (characters per line) for the screen buffer.

Parameters

Parameter | Description
columns | Desired buffer width in character columns.

Examples

WIDTH 80       ' standard 80-column mode
WIDTH 132      ' wide mode (132 columns)

Assembler Output

; PBXA64 x64 assembly for WIDTH
mov rcx, [rbp-8]          ; column count
call __pb_width            ; calls SetConsoleScreenBufferSize

See Also

  • LOCATE
  • CLS
  • COLOR


BEEP - PBXA64 Compiler Help

BEEP

Sounds a beep through the computer speaker.

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

BEEP

Description

BEEP emits an audible tone through the system speaker. The runtime helper calls the Windows Beep API with a default frequency of 800 Hz and a duration of 200 milliseconds. In modern Windows versions, Beep() generates a tone through the built-in PC speaker or the default audio device, depending on system configuration. BEEP takes no arguments and requires no parameters.

Examples

BEEP
PRINT "Beep sounded"
IF error THEN BEEP

Assembler Output

; PBXA64 x64 assembly for BEEP
mov ecx, 800              ; frequency (Hz)
mov edx, 200              ; duration (ms)
call __imp_Beep            ; Windows Beep API

See Also

  • PRINT


LPRINT - PBXA64 Compiler Help

LPRINT

Outputs expressions to the default printer (LPT1).

Kind: Statement | Category: Console / Text I/O

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

LPRINT expr1, expr2, ...
LPRINT expr1; expr2; ...

Description

LPRINT outputs text to the parallel port printer (LPT1:). The runtime helper opens \\.\LPT1 using CreateFileA with GENERIC_WRITE access, writes the formatted output with WriteFile, and then closes the handle. Commas separate expressions with tab stops; semicolons concatenate without spacing. LPRINT automatically appends a CRLF unless the statement ends with a semicolon or comma. LPRINT does not spool to the Windows print subsystem; it writes directly to the LPT port.

Parameters

expr — one or more expressions (numeric or string) to print.

Parameters

Parameter | Description
expr | Expression(s) to output to the printer.

Examples

LPRINT "Hello, Printer!"
LPRINT "Line 1"; "Line 2"
LPRINT "Column1", "Column2"

Assembler Output

; PBXA64 x64 assembly for LPRINT
lea rcx, [rbp-8]          ; expression value or descriptor
call __pb_lprint           ; opens \\.\LPT1, writes, closes handle

; Internal: CreateFileA("\\.\LPT1", GENERIC_WRITE, ...)
; WriteFile(hFile, data, len, &written, NULL)
; CloseHandle(hFile)

See Also

  • PRINT
  • OPEN


THREAD CREATE - PBXA64 Compiler Help

THREAD CREATE

Creates a new thread that executes a SUB procedure.

Kind: Statement | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

THREAD CREATE threadfunc TO handle

Description

THREAD CREATE starts a new thread executing the specified SUB procedure. The thread function must be a SUB (not FUNCTION). The handle variable receives a LONG thread handle that can be used with other threading statements. The runtime helper calls CreateThread with a start address pointing to a thunk that calls the target SUB. The thread starts immediately upon creation. The calling program continues execution concurrently with the new thread.

Parameters

threadfunc — name of the SUB procedure to run in the new thread.
handle — LONG variable that receives the thread handle.

Parameters

Parameter | Description
threadfunc | SUB procedure name to execute in the new thread.
handle | LONG variable receiving the thread handle.

Examples

THREAD CREATE MyWorker TO hThread
' ... main thread continues concurrently ...
THREAD CLOSE hThread

SUB MyWorker()
  PRINT "Worker thread running"
END SUB

Assembler Output

; PBXA64 x64 assembly for THREAD CREATE
lea rcx, [MyWorker]        ; thread function address
lea rdx, [rbp-8]           ; address of handle variable
call __pb_thread_create     ; calls CreateThread(NULL, 0, addr, param, 0, &tid)
mov [rbp-8], eax            ; store thread handle

See Also

  • THREAD CLOSE
  • THREAD STATUS
  • THREAD SUSPEND
  • THREAD RESUME
  • XLAUNCH


THREAD CLOSE - PBXA64 Compiler Help

THREAD CLOSE

Closes a thread handle and waits for the thread to terminate.

Kind: Statement | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

THREAD CLOSE handle

Description

THREAD CLOSE waits for the specified thread to finish execution and then closes the thread handle. The runtime helper calls WaitForSingleObject with an INFINITE timeout to wait for the thread to exit, then calls CloseHandle to release the thread handle. After THREAD CLOSE returns, the handle variable is invalid and should not be used with other threading functions. If the thread has already terminated, CloseHandle is called immediately.

Parameters

handle — LONG variable containing a valid thread handle from THREAD CREATE.

Parameters

Parameter | Description
handle | Thread handle to close. Must be valid.

Examples

THREAD CREATE MyWorker TO hThread
THREAD CLOSE hThread     ' wait for completion and close

Assembler Output

; PBXA64 x64 assembly for THREAD CLOSE
mov rcx, [rbp-8]           ; thread handle
call __pb_thread_close      ; WaitForSingleObject + CloseHandle

See Also

  • THREAD CREATE
  • THREAD STATUS
  • WAITFOR


THREAD STATUS - PBXA64 Compiler Help

THREAD STATUS

Returns the execution status of a thread.

Kind: Function | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

status = THREAD STATUS(handle)

Description

THREAD STATUS returns the execution status of the specified thread. The return value is a LONG: -1 indicates the thread handle is invalid or has been closed; 0 indicates the thread is still running; any other value is the thread's exit code (the thread has terminated). The runtime helper calls GetExitCodeThread to query the thread state. If the thread has exited, the exit code is returned. THREAD STATUS does not modify the thread or its handle.

Parameters

handle — LONG variable containing a valid thread handle.

Parameters

Parameter | Description
handle | Thread handle to query.

Examples

THREAD CREATE MyWorker TO hThread
DO
  status = THREAD STATUS(hThread)
  IF status <> 0 THEN EXIT DO
  SLEEP 100
LOOP
PRINT "Thread exited with code: "; status
THREAD CLOSE hThread

Assembler Output

; PBXA64 x64 assembly for THREAD STATUS
mov rcx, [rbp-8]           ; thread handle
call __pb_thread_status     ; calls GetExitCodeThread
mov [rbp-16], eax           ; store result

; Returns:
; -1 = invalid handle
; 0 = still running
; nonzero = thread exit code

See Also

  • THREAD CREATE
  • THREAD CLOSE
  • THREADCOUNT


THREAD SUSPEND - PBXA64 Compiler Help

THREAD SUSPEND

Suspends execution of a running thread.

Kind: Statement | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

THREAD SUSPEND handle

Description

THREAD SUSPEND suspends the specified thread, halting its execution until it is resumed with THREAD RESUME. The runtime helper calls SuspendThread, which suspends the thread and increments its suspend count. Multiple calls to THREAD SUSPEND require an equal number of THREAD RESUME calls to resume execution. Suspending a thread that owns synchronization objects (mutexes, critical sections) can cause deadlocks. Use with caution.

Parameters

handle — LONG variable containing a valid thread handle.

Parameters

Parameter | Description
handle | Thread handle to suspend.

Examples

THREAD CREATE MyWorker TO hThread
THREAD SUSPEND hThread
' ... thread is paused ...
THREAD RESUME hThread

Assembler Output

; PBXA64 x64 assembly for THREAD SUSPEND
mov rcx, [rbp-8]           ; thread handle
call __pb_thread_suspend    ; calls SuspendThread(handle)

See Also

  • THREAD RESUME
  • THREAD CREATE
  • THREAD STATUS


THREAD RESUME - PBXA64 Compiler Help

THREAD RESUME

Resumes execution of a suspended thread.

Kind: Statement | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

THREAD RESUME handle

Description

THREAD RESUME decrements the suspend count of a previously suspended thread. When the suspend count reaches zero, the thread resumes execution. The runtime helper calls ResumeThread. If the thread was not suspended (suspend count already zero), ResumeThread returns an error code and has no effect. Each THREAD SUSPEND call must be matched with a corresponding THREAD RESUME call to fully resume the thread.

Parameters

handle — LONG variable containing a valid thread handle.

Parameters

Parameter | Description
handle | Thread handle to resume.

Examples

THREAD CREATE MyWorker TO hThread
THREAD SUSPEND hThread
' ... do work while thread is paused ...
THREAD RESUME hThread     ' thread continues execution

Assembler Output

; PBXA64 x64 assembly for THREAD RESUME
mov rcx, [rbp-8]           ; thread handle
call __pb_thread_resume     ; calls ResumeThread(handle)

See Also

  • THREAD SUSPEND
  • THREAD CREATE
  • THREAD STATUS


THREADCOUNT - PBXA64 Compiler Help

THREADCOUNT

Returns the number of active threads created by the program.

Kind: Function | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

count = THREADCOUNT

Description

THREADCOUNT returns the current number of active threads managed by the PBXA64 runtime. The count is maintained in a global variable (__pb_thread_count) that is incremented on THREAD CREATE and decremented on thread termination. Only threads created via THREAD CREATE are tracked; threads created directly via the Windows API are not counted. The function takes no arguments.

Return Value

A LONG containing the number of active threads.

Examples

THREAD CREATE MyWorker TO h1
THREAD CREATE MyWorker TO h2
PRINT "Active threads: "; THREADCOUNT   ' prints 2

Assembler Output

; PBXA64 x64 assembly for THREADCOUNT
mov rax, [__pb_thread_count] ; read global thread counter
mov [rbp-8], eax             ; store result

See Also

  • THREAD CREATE
  • THREAD CLOSE
  • THREAD STATUS


XLAUNCH - PBXA64 Compiler Help

XLAUNCH

Launches a thread that executes a FUNCTION and returns a result.

Kind: Statement | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

XLAUNCH func(args) TO handle

Description

XLAUNCH (eXecute LAUNCH) creates a new thread to execute a FUNCTION with specified arguments. Unlike THREAD CREATE, XLAUNCH supports passing arguments to the target function and can retrieve the function's return value via WAITFOR. The runtime helper allocates a parameter block on the heap, copies the arguments, and calls CreateThread with a thunk that calls the function and stores the return value. The handle receives a thread handle that can be used with WAITFOR to retrieve the result.

Parameters

func(args) — function name with argument list to execute in the new thread.
handle — LONG variable receiving the thread handle.

Parameters

Parameter | Description
func(args) | Function call expression to execute in the thread.
handle | Variable receiving the thread handle.

Examples

XLAUNCH ComputeResult(42, 100) TO hThread
WAITFOR hThread TO result&
PRINT "Result: "; result&

Assembler Output

; PBXA64 x64 assembly for XLAUNCH
lea rcx, [ComputeResult]   ; function address
lea rdx, [rbp-8]           ; argument block
mov r8d, [argCount]        ; number of arguments
lea r9, [rbp-16]           ; handle variable address
call __pb_xlaunch           ; allocate param block, CreateThread

; Internal: heap-allocated parameter block
; CreateThread(NULL, 0, thunk, paramBlock, 0, &tid)

See Also

  • WAITFOR
  • THREAD CREATE
  • THREAD STATUS


WAITFOR - PBXA64 Compiler Help

WAITFOR

Waits for a thread created by XLAUNCH to finish and retrieves its return value.

Kind: Statement | Category: Threading

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

WAITFOR handle TO result

Description

WAITFOR waits for the thread associated with the given handle to finish execution, then retrieves the return value from the thread's function. The runtime helper calls WaitForSingleObject with INFINITE timeout to block until the thread exits, then reads the return value from the thread's parameter block, and finally calls CloseHandle to release the thread handle. WAITFOR is specifically designed to complement XLAUNCH; for threads created with THREAD CREATE, use THREAD CLOSE instead.

Parameters

handle — LONG containing a thread handle from XLAUNCH.
result — variable that receives the thread function's return value.

Parameters

Parameter | Description
handle | Thread handle from a previous XLAUNCH call.
result | Variable to receive the function return value.

Examples

XLAUNCH ComputeResult(42) TO hThread
WAITFOR hThread TO result&
PRINT "Returned: "; result&

Assembler Output

; PBXA64 x64 assembly for WAITFOR
mov rcx, [rbp-8]           ; thread handle
lea rdx, [rbp-16]          ; address of result variable
call __pb_waitfor           ; WaitForSingleObject + read result + CloseHandle

See Also

  • XLAUNCH
  • THREAD CREATE
  • THREAD CLOSE


DIALOG NEW - PBXA64 Compiler Help

DIALOG NEW

Creates a new dialog window.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG NEW hDlg, title$, x, y, w, h [, dStyle] [, dExStyle] [, hParent]

Description

Creates a new dialog window and assigns its handle to hDlg. Parameters are the dialog handle variable, window title, position (x, y), size (w, h), optional style flags, extended style flags, and optional parent window handle. Default style includes WS_CAPTION | WS_SYSMENU | WS_VISIBLE.

Examples

LOCAL hDlg AS LONG
DIALOG NEW hDlg, "My Dialog", 100, 100, 400, 300
DIALOG SHOW MODAL hDlg

Assembler Output

; DIALOG NEW calls CreateWindowExA internally
mov ecx, dword ptr [hDlg_addr]
lea edx, [title_string]
mov r8d, 100 ; x
mov r9d, 100 ; y
call __pb_dialog_new

See Also

  • DIALOG SHOW
  • DIALOG CLOSE


DIALOG SHOW - PBXA64 Compiler Help

DIALOG SHOW

Displays a dialog window modally or modelessly.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG SHOW MODAL hDlg [, hParent]
DIALOG SHOW MODELESS hDlg [, nCmdShow]

Description

DIALOG SHOW MODAL displays the dialog modally, blocking execution until the dialog is dismissed. An optional parent handle can be specified. DIALOG SHOW MODELESS displays the dialog modelessly and returns immediately; the optional nCmdShow controls initial visibility (default SW_SHOW). Modal dialogs run their own message loop internally.

Examples

DIALOG SHOW MODAL hDlg
' vs
DIALOG SHOW MODELESS hDlg

Assembler Output

; MODAL: calls DialogBoxParam / runtime modal loop
mov ecx, dword ptr [hDlg]
call __pb_dialog_show_modal
; MODELESS: calls ShowWindow
mov ecx, dword ptr [hDlg]
xor edx, edx  ; SW_SHOW = 5 normally
call __pb_dialog_show_modeless

See Also

  • DIALOG NEW
  • DIALOG CLOSE


DIALOG CLOSE - PBXA64 Compiler Help

DIALOG CLOSE

Closes a dialog window.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG CLOSE hDlg

Description

Sends WM_CLOSE to the dialog identified by hDlg. For modal dialogs this ends the modal loop; for modeless dialogs it destroys the window. After closing, the handle is invalidated.

Examples

DIALOG CLOSE hDlg

Assembler Output

; DIALOG CLOSE sends WM_CLOSE
mov ecx, dword ptr [hDlg]
call __pb_dialog_close

See Also

  • DIALOG NEW
  • DIALOG SHOW


DIALOG SET TEXT - PBXA64 Compiler Help

DIALOG SET TEXT

Sets the caption text of a dialog window.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG SET TEXT hDlg, title$

Description

Changes the window title (caption) of the dialog identified by hDlg to the string title$. Internally calls SetWindowTextA on the dialog handle.

Examples

DIALOG SET TEXT hDlg, "New Title"

Assembler Output

; DIALOG SET TEXT calls SetWindowTextA
mov ecx, dword ptr [hDlg]
lea edx, [title_string]
call SetWindowTextA

See Also

  • DIALOG GET TEXT
  • CONTROL SET TEXT


DIALOG GET TEXT - PBXA64 Compiler Help

DIALOG GET TEXT

Retrieves the caption text of a dialog window.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG GET TEXT hDlg TO var$

Description

Retrieves the current window caption of the dialog identified by hDlg and stores it in the string variable var$. Internally calls GetWindowTextA. The string variable must be a PB string (PB_STRING64).

Examples

LOCAL title$ AS STRING
DIALOG GET TEXT hDlg TO title$
MSGBOX "Title: " + title$

Assembler Output

; DIALOG GET TEXT calls GetWindowTextA
mov ecx, dword ptr [hDlg]
lea edx, [buffer]
mov r8d, 256
call GetWindowTextA
; then copies to PB_STRING64 descriptor

See Also

  • DIALOG SET TEXT


DIALOG ENABLE / DISABLE - PBXA64 Compiler Help

DIALOG ENABLE / DIALOG DISABLE

Enables or disables a dialog window, controlling user interaction.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG ENABLE hDlg
DIALOG DISABLE hDlg

Description

DIALOG ENABLE restores user interaction with a dialog window that was previously disabled. DIALOG DISABLE prevents all mouse and keyboard input to the dialog. Internally calls the Win32 API EnableWindow(hWnd, TRUE) for ENABLE or EnableWindow(hWnd, FALSE) for DISABLE. Useful for modal operations within modeless dialogs or to temporarily prevent input during background processing.

Examples

DIALOG DISABLE hDlg     ' prevent user input
' ... do background work ...
DIALOG ENABLE hDlg      ' re-enable user input

Assembler Output

; DIALOG ENABLE
 mov ecx, dword ptr [hDlg]   ; hWnd
 mov edx, 1                  ; TRUE
 call EnableWindow
; DIALOG DISABLE
 mov ecx, dword ptr [hDlg]   ; hWnd
 xor edx, edx                ; FALSE
 call EnableWindow

See Also

  • DIALOG NEW
  • DIALOG SHOW
  • DIALOG CLOSE
  • Back to command index


DIALOG SEND - PBXA64 Compiler Help

DIALOG SEND

Sends a Windows message to a dialog (synchronous).

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG SEND hDlg, msg, wParam, lParam

Description

Sends a Windows message to the dialog identified by hDlg. The call blocks until the message is processed (synchronous). msg is the message identifier, wParam and lParam are message parameters. Internally calls SendMessageA. The return value can be captured by assigning the result to a variable: result = DIALOG SEND ...

Examples

' Close the dialog
DIALOG SEND hDlg, %WM_CLOSE, 0, 0

Assembler Output

; DIALOG SEND calls SendMessageA
mov ecx, dword ptr [hDlg]
mov edx, WM_CLOSE
xor r8d, r8d     ; wParam = 0
xor r9d, r9d     ; lParam = 0
call SendMessageA

See Also

  • DIALOG POST
  • CONTROL SEND


DIALOG POST - PBXA64 Compiler Help

DIALOG POST

Posts a Windows message to a dialog (asynchronous).

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

DIALOG POST hDlg, msg, wParam, lParam

Description

Posts a Windows message to the dialog's message queue and returns immediately (asynchronous). msg is the message identifier, wParam and lParam are message parameters. Internally calls PostMessageA. Unlike DIALOG SEND, this does not wait for the message to be processed.

Examples

' Close the dialog asynchronously
DIALOG POST hDlg, %WM_CLOSE, 0, 0

Assembler Output

; DIALOG POST calls PostMessageA
mov ecx, dword ptr [hDlg]
mov edx, WM_CLOSE
xor r8d, r8d     ; wParam = 0
xor r9d, r9d     ; lParam = 0
call PostMessageA

See Also

  • DIALOG SEND


CONTROL ADD - PBXA64 Compiler Help

CONTROL ADD

Adds a control to a dialog window.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

CONTROL ADD className$, hDlg, id, text$, x, y, w, h [, style] [, exStyle]

Description

Creates a child control window on the specified dialog. className$ is the Windows class name (e.g. "Button", "Edit", "Static", "ListBox", "ComboBox"). hDlg is the parent dialog handle, id is the control identifier, text$ is the initial caption. Position and size are in dialog units. Optional style and exStyle override default styles.

Examples

CONTROL ADD "Button", hDlg, 100, "OK", 150, 260, 80, 25
CONTROL ADD "Edit", hDlg, 200, "", 20, 20, 360, 200

Assembler Output

; CONTROL ADD calls CreateWindowExA
mov ecx, dword ptr [hDlg]
lea edx, [class_name]
mov r8d, 100       ; id
lea r9d, [ctrl_text]
call __pb_control_add

See Also

  • CONTROL SET TEXT
  • CONTROL GET TEXT


CONTROL SET TEXT - PBXA64 Compiler Help

CONTROL SET TEXT

Sets the text of a dialog control.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

CONTROL SET TEXT hDlg, id, text$

Description

Sets the caption or text content of the control identified by its parent dialog hDlg and control id. Internally calls GetDlgItem to obtain the control handle, then SetWindowTextA to set the text.

Examples

CONTROL SET TEXT hDlg, 200, "New text value"

Assembler Output

; CONTROL SET TEXT calls SetWindowTextA on the control
mov ecx, dword ptr [hDlg]
mov edx, 200        ; id
lea r8d, [new_text]
call __pb_control_set_text

See Also

  • CONTROL GET TEXT


CONTROL GET TEXT - PBXA64 Compiler Help

CONTROL GET TEXT

Retrieves the text of a dialog control.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

CONTROL GET TEXT hDlg, id TO var$

Description

Retrieves the text content of the control identified by its parent dialog hDlg and control id. The result is stored in var$. Internally calls GetDlgItem then GetWindowTextA.

Examples

LOCAL text$ AS STRING
CONTROL GET TEXT hDlg, 200 TO text$
MSGBOX "Edit box contains: " + text$

Assembler Output

; CONTROL GET TEXT calls GetWindowTextA
mov ecx, dword ptr [hDlg]
mov edx, 200        ; id
lea r8d, [buffer]
call __pb_control_get_text
; result stored in PB_STRING64 descriptor

See Also

  • CONTROL SET TEXT


CONTROL SET STATE - PBXA64 Compiler Help

CONTROL SET STATE

Sets the check/state of a dialog control (e.g. checkbox, radio button).

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

CONTROL SET STATE hDlg, id, state

Description

Sets the check state of a button-style control (checkbox, radio button, auto-checkbox). state can be %BST_UNCHECKED (0), %BST_CHECKED (1), or %BST_INDETERMINATE (2). Internally calls CheckDlgButton.

Examples

CONTROL SET STATE hDlg, 300, %BST_CHECKED

Assembler Output

; CONTROL SET STATE calls CheckDlgButton
mov ecx, dword ptr [hDlg]
mov edx, 300        ; id
mov r8d, 1          ; BST_CHECKED
call CheckDlgButton

See Also

  • CONTROL GET STATE


CONTROL GET STATE - PBXA64 Compiler Help

CONTROL GET STATE

Retrieves the check state of a dialog control.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

CONTROL GET STATE hDlg, id TO var

Description

Retrieves the check state of a button-style control and stores it in var. The return value is %BST_UNCHECKED (0) or %BST_CHECKED (1). Internally calls IsDlgButtonChecked.

Examples

LOCAL state AS LONG
CONTROL GET STATE hDlg, 300 TO state
IF state = %BST_CHECKED THEN
    MSGBOX "Checkbox is checked"
END IF

Assembler Output

; CONTROL GET STATE calls IsDlgButtonChecked
mov ecx, dword ptr [hDlg]
mov edx, 300
call IsDlgButtonChecked
mov dword ptr [var], eax

See Also

  • CONTROL SET STATE


MENU NEW - PBXA64 Compiler Help

MENU NEW

Creates a new menu bar or popup menu.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

MENU NEW BAR TO hMenu
MENU NEW POPUP TO hMenu

Description

Creates a new menu handle. MENU NEW BAR creates a menu bar (top-level menu for a window). MENU NEW POPUP creates a popup (drop-down) menu that can be used as a submenu or shown as a context menu. The resulting handle is stored in hMenu.

Examples

LOCAL hMenu AS LONG
MENU NEW BAR TO hMenu

Assembler Output

; MENU NEW BAR calls CreateMenu
call CreateMenu
mov dword ptr [hMenu], eax
; MENU NEW POPUP calls CreatePopupMenu
call CreatePopupMenu
mov dword ptr [hMenu], eax

See Also

  • MENU ADD
  • MENU ATTACH


MENU ADD - PBXA64 Compiler Help

MENU ADD

Adds a menu item or popup submenu to an existing menu.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

MENU ADD STRING, hMenu, id, "text"
MENU ADD POPUP, hMenu, id, "text"

Description

Adds an item to the menu identified by hMenu. MENU ADD STRING adds a clickable menu item with the specified id. MENU ADD POPUP adds a submenu item — id must be a menu handle created with MENU NEW POPUP. Internally calls AppendMenuA.

Examples

MENU ADD STRING, hMenu, 101, "&Open"
MENU ADD STRING, hMenu, 102, "&Save"
MENU ADD STRING, hMenu, 0, ""   ' separator
MENU ADD POPUP, hMenu, hSub, "&Recent"

Assembler Output

; MENU ADD STRING calls AppendMenuA
mov ecx, dword ptr [hMenu]
mov edx, %MF_STRING
mov r8d, 101        ; id
lea r9d, [item_text]
call AppendMenuA

See Also

  • MENU NEW
  • MENU ATTACH


MENU ATTACH - PBXA64 Compiler Help

MENU ATTACH

Attaches a menu bar to a dialog window.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

MENU ATTACH hMenu, hDlg

Description

Attaches the menu identified by hMenu to the dialog hDlg. This sets the dialog's window menu. The menu should have been created with MENU NEW BAR and populated with MENU ADD. Internally calls SetMenu.

Examples

MENU NEW BAR TO hMenu
MENU ADD STRING, hMenu, 101, "&Exit"
MENU ATTACH hMenu, hDlg

Assembler Output

; MENU ATTACH calls SetMenu
mov ecx, dword ptr [hDlg]
mov edx, dword ptr [hMenu]
call SetMenu

See Also

  • MENU NEW
  • MENU SHOW POPUP


MENU SHOW POPUP - PBXA64 Compiler Help

MENU SHOW POPUP

Displays a popup (context) menu at the current cursor position.

Kind: Statement | Category: GUI / DDT

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

MENU SHOW POPUP hMenu

Description

Shows a popup menu at the current mouse cursor position. The menu should have been created with MENU NEW POPUP and populated. The call blocks until the user selects an item or dismisses the menu. Internally calls TrackPopupMenu with TPM_LEFTALIGN | TPM_TOPALIGN flags.

Examples

MENU SHOW POPUP hPopup

Assembler Output

; MENU SHOW POPUP calls TrackPopupMenu
mov ecx, dword ptr [hMenu]
xor edx, edx        ; TPM_LEFTALIGN
call GetCursorPos
mov r8d, cursor_x
mov r9d, cursor_y
push 0              ; hWnd = NULL
call TrackPopupMenu

See Also

  • MENU NEW
  • MENU ATTACH


GRAPHIC WINDOW - PBXA64 Compiler Help

GRAPHIC WINDOW

Creates a graphics window for drawing.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC WINDOW "title", x, y, w, h TO hWin

Description

Creates a dedicated graphics window for 2D drawing operations. The window has a client area of the specified size. The handle hWin receives the window handle for subsequent GRAPHIC operations. The window is automatically shown upon creation.

Examples

LOCAL hWin AS LONG
GRAPHIC WINDOW "Drawing", 100, 100, 640, 480 TO hWin

Assembler Output

; GRAPHIC WINDOW creates a window for GDI drawing
lea rcx, [title_str]
mov edx, 100       ; x
mov r8d, 100       ; y
mov r9d, 640       ; w
push 480           ; h
call __pb_graphic_window
mov dword ptr [hWin], eax

See Also

  • GRAPHIC LINE
  • GRAPHIC BOX


GRAPHIC LINE - PBXA64 Compiler Help

GRAPHIC LINE

Draws a line or unfilled rectangle in a graphics window.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC LINE hWin, (x1,y1)-(x2,y2) [, color]
GRAPHIC LINE hWin, (x1,y1)-(x2,y2), , B [, color]

Description

Draws a line from (x1,y1) to (x2,y2) in the specified graphics window. With the B (Box) option, draws an unfilled rectangle with corners at the two coordinate pairs. The optional color parameter specifies the RGB color; the current GRAPHIC COLOR is used if omitted.

Examples

GRAPHIC LINE hWin, (10,10)-(200,10)
GRAPHIC LINE hWin, (50,50)-(150,100), , B

Assembler Output

; GRAPHIC LINE calls MoveToEx + LineTo (or Rectangle for B)
mov ecx, dword ptr [hWin]
mov edx, 10        ; x1
mov r8d, 10        ; y1
mov r9d, 200       ; x2
push 10            ; y2
call __pb_graphic_line

See Also

  • GRAPHIC BOX
  • GRAPHIC CIRCLE


GRAPHIC BOX - PBXA64 Compiler Help

GRAPHIC BOX

Draws a filled rectangle in a graphics window.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC BOX hWin, (x1,y1)-(x2,y2) [, color] [, fillColor]

Description

Draws a filled rectangle with corners at (x1,y1) and (x2,y2). The optional color sets the border color and fillColor sets the interior fill. If omitted, the current GRAPHIC COLOR settings apply. Internally uses GDI CreateSolidBrush and Rectangle or FillRect.

Examples

GRAPHIC BOX hWin, (20,20)-(100,80)

Assembler Output

; GRAPHIC BOX creates brush and fills rectangle
mov ecx, dword ptr [hWin]
mov edx, 20
mov r8d, 20
mov r9d, 100
push 80
call __pb_graphic_box

See Also

  • GRAPHIC LINE
  • GRAPHIC CLEAR


GRAPHIC CIRCLE - PBXA64 Compiler Help

GRAPHIC CIRCLE

Draws a circle or ellipse in a graphics window.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC CIRCLE hWin, (x,y), radius [, color] [, fill]
GRAPHIC CIRCLE hWin, (x,y), rx, ry [, color] [, fill]

Description

Draws a circle or ellipse centered at (x,y) in the graphics window. The first form draws a circle with the given radius. The second form draws an ellipse with separate x-radius and y-radius. Optional color sets the outline, and fill if non-zero fills the shape. Internally uses GDI Ellipse or Arc.

Examples

GRAPHIC CIRCLE hWin, (320,240), 100
GRAPHIC CIRCLE hWin, (320,240), 100, 50

Assembler Output

; GRAPHIC CIRCLE calls Ellipse
mov ecx, dword ptr [hWin]
mov edx, 320       ; cx
mov r8d, 240       ; cy
mov r9d, 100       ; rx
push 100           ; ry
call __pb_graphic_circle

See Also

  • GRAPHIC LINE
  • GRAPHIC BOX


GRAPHIC SET - PBXA64 Compiler Help

GRAPHIC SET (Pixel)

Sets a single pixel to a specified color.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC SET hWin, (x,y), color

Description

Sets the pixel at coordinates (x,y) in the graphics window to the specified RGB color value. Internally calls GDI SetPixel. This is the lowest-level drawing operation.

Examples

GRAPHIC SET hWin, (10,10), %RGB_RED

Assembler Output

; GRAPHIC SET calls SetPixel
mov ecx, dword ptr [hWin]
mov edx, 10        ; x
mov r8d, 10        ; y
mov r9d, RGB_RED   ; color
call __pb_graphic_set_pixel

See Also

  • GRAPHIC GET (Pixel)
  • GRAPHIC CLEAR


GRAPHIC GET - PBXA64 Compiler Help

GRAPHIC GET (Pixel)

Retrieves the color value of a single pixel.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC GET hWin, (x,y) TO var

Description

Retrieves the RGB color value of the pixel at (x,y) in the graphics window and stores it in var. Internally calls GDI GetPixel. The return value is a 24-bit RGB color (&H00BBGGRR). Returns -1 (CLR_INVALID) if the coordinates are out of range.

Examples

LOCAL pixel AS LONG
GRAPHIC GET hWin, (100,50) TO pixel

Assembler Output

; GRAPHIC GET calls GetPixel
mov ecx, dword ptr [hWin]
mov edx, 100       ; x
mov r8d, 50        ; y
call __pb_graphic_get_pixel
mov dword ptr [pixel], eax

See Also

  • GRAPHIC SET (Pixel)


GRAPHIC CLEAR - PBXA64 Compiler Help

GRAPHIC CLEAR

Clears the graphics window to the specified color (or white).

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC CLEAR hWin [, color]

Description

Fills the entire client area of the graphics window with the specified RGB color. If color is omitted, the window is cleared to white (%RGB_WHITE or &H00FFFFFF). Internally creates a solid brush and calls FillRect or PatBlt.

Examples

GRAPHIC CLEAR hWin
GRAPHIC CLEAR hWin, %RGB_BLACK

Assembler Output

; GRAPHIC CLEAR fills with brush
mov ecx, dword ptr [hWin]
mov edx, RGB_WHITE
call __pb_graphic_clear

See Also

  • GRAPHIC COLOR


GRAPHIC PRINT - PBXA64 Compiler Help

GRAPHIC PRINT

Draws text in a graphics window.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC PRINT hWin, text$ [, x, y]

Description

Draws text in the graphics window using the current GRAPHIC COLOR foreground setting. If (x,y) is omitted, text is drawn at the current text cursor position (which advances with each PRINT). Internally calls GDI TextOutA or DrawTextA with the selected font.

Examples

GRAPHIC PRINT hWin, "Hello, Graphics!"
GRAPHIC PRINT hWin, "At coordinates", 100, 200

Assembler Output

; GRAPHIC PRINT calls TextOutA
mov ecx, dword ptr [hWin]
lea edx, [text_str]
mov r8d, 100       ; x
mov r9d, 200       ; y
call __pb_graphic_print_text

See Also

  • GRAPHIC COLOR
  • GRAPHIC CLEAR


GRAPHIC COLOR - PBXA64 Compiler Help

GRAPHIC COLOR

Sets the foreground and optional background drawing colors.

Kind: Statement | Category: GUI / Graphics

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

GRAPHIC COLOR hWin, fg [, bg]

Description

Sets the foreground text/drawing color and optionally the background color for subsequent GRAPHIC operations in the specified window. fg and bg are RGB color values. Internally creates GDI pens and brushes with the specified colors for future drawing commands.

Examples

GRAPHIC COLOR hWin, %RGB_RED, %RGB_WHITE
GRAPHIC PRINT hWin, "This text is red"

Assembler Output

; GRAPHIC COLOR sets GDI pen and brush
mov ecx, dword ptr [hWin]
mov edx, RGB_RED
mov r8d, RGB_WHITE
call __pb_graphic_color

See Also

  • GRAPHIC CLEAR
  • GRAPHIC PRINT


TCP OPEN - PBXA64 Compiler Help

TCP OPEN

Opens a TCP connection to a remote host.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP OPEN "host:port" AS #fnum

Description

Establishes a TCP connection to the specified host and port. host can be a hostname or IP address. #fnum is a file number used to reference the connection in subsequent TCP operations. Internally creates a Winsock socket, resolves the hostname via getaddrinfo, and calls connect.

Examples

TCP OPEN "example.com:80" AS #1

Assembler Output

; TCP OPEN calls Winsock connect()
lea rcx, [host_port_str]
mov edx, 1         ; file number
call __pb_tcp_open
; internally: WSAStartup, socket(), connect()

See Also

  • TCP CLOSE
  • TCP SEND


TCP CLOSE - PBXA64 Compiler Help

TCP CLOSE

Closes a TCP connection.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP CLOSE #fnum

Description

Closes the TCP connection associated with file number #fnum. Internally calls shutdown on the socket to gracefully terminate the connection, then closesocket to release the Winsock socket handle. The file number becomes available for reuse.

Examples

TCP CLOSE #1

Assembler Output

; TCP CLOSE calls closesocket()
mov edx, 1         ; file number
call __pb_tcp_close
; internally: shutdown(s, SD_BOTH), closesocket(s)

See Also

  • TCP OPEN


TCP SEND - PBXA64 Compiler Help

TCP SEND

Sends data over a TCP connection.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP SEND #fnum, data$

Description

Sends the string data$ over the TCP connection identified by #fnum. The entire string is sent; partial sends are handled internally by the runtime. Internally calls Winsock send with the string data and length.

Examples

TCP SEND #1, "GET / HTTP/1.0" + $CRLF + $CRLF

Assembler Output

; TCP SEND calls send()
mov edx, 1         ; file number
lea rcx, [data_buffer]
mov r8d, [data_length]
call __pb_tcp_send
; internally: send(socket, buf, len, 0)

See Also

  • TCP RECV
  • TCP PRINT


TCP RECV - PBXA64 Compiler Help

TCP RECV

Receives data from a TCP connection.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP RECV #fnum, n TO var$

Description

Receives up to n bytes of data from the TCP connection #fnum and stores the result in the string variable var$. The actual number of bytes received may be less than n. If the connection is closed, an empty string is returned. Internally calls Winsock recv.

Examples

LOCAL response$ AS STRING
TCP RECV #1, 4096 TO response$
MSGBOX "Received: " + response$

Assembler Output

; TCP RECV calls recv()
mov edx, 1         ; file number
mov r8d, 4096      ; max bytes
lea r9d, [buffer]
call __pb_tcp_recv
; result stored in PB_STRING64 descriptor

See Also

  • TCP SEND


TCP ACCEPT - PBXA64 Compiler Help

TCP ACCEPT

Accepts an incoming TCP connection on a listening socket.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP ACCEPT #listener TO #client

Description

TCP ACCEPT accepts an incoming connection on a previously opened listening socket (#listener) and creates a new connected socket identified by #client. The listener socket must have been opened with TCP OPEN "port" AS #listener (server mode). Internally calls the Winsock accept() function, which returns a new socket descriptor. The call blocks until a connection is available (use TCP NOTIFY for non-blocking operation). The #client handle is used for subsequent TCP SEND/TCP RECV operations.

Examples

TCP OPEN "8080" AS #1     ' listen on port 8080
TCP ACCEPT #1 TO #2       ' accept incoming connection
TCP SEND #2, "Hello"      ' send to connected client

Assembler Output

; TCP ACCEPT
 mov ecx, dword ptr [listener_fd]
 call __pb_tcp_accept
 mov dword ptr [client_fd], eax
; internally: accept(sock, &addr, &addrlen)

See Also

  • TCP OPEN
  • TCP CLOSE
  • TCP NOTIFY
  • Back to command index


TCP NOTIFY - PBXA64 Compiler Help

TCP NOTIFY

Registers for TCP socket event notification.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP NOTIFY #fnum, mask

Description

TCP NOTIFY registers for Winsock event notification on a TCP socket. The mask parameter specifies a combination of network event flags (FD_READ, FD_WRITE, FD_ACCEPT, FD_CONNECT, FD_CLOSE). Internally calls WSAEventSelect(sock, hEvent, lNetworkEvents) to associate events with an event object. The application can then wait on the event handle to determine when the socket has data available, is ready to send, or has a connection request.

Examples

TCP NOTIFY #1, %FD_READ OR %FD_CLOSE

Assembler Output

; TCP NOTIFY
 mov ecx, dword ptr [fnum]
 mov edx, dword ptr [mask]
 call __pb_tcp_notify
; internally: WSAEventSelect(sock, event, mask)

See Also

  • TCP OPEN
  • TCP CLOSE
  • TCP ACCEPT
  • Back to command index


TCP LINE INPUT - PBXA64 Compiler Help

TCP LINE INPUT

Reads a line of text from a TCP connection.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP LINE INPUT #fnum, strvar$

Description

Reads a line of text from the TCP connection #fnum into the string variable strvar$. A line is terminated by CRLF ($CRLF). The line terminator is stripped from the result. Internally buffers incoming data and scans for the terminator.

Examples

LOCAL line$ AS STRING
TCP LINE INPUT #1, line$
MSGBOX "Received line: " + line$

Assembler Output

; TCP LINE INPUT reads until CRLF
mov edx, 1
lea rcx, [strvar_descriptor]
call __pb_tcp_line_input
; internally: recv into buffer, scan for CRLF, copy to PB_STRING64

See Also

  • TCP RECV
  • TCP PRINT


TCP PRINT - PBXA64 Compiler Help

TCP PRINT

Sends text data over a TCP connection with automatic CRLF termination.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

TCP PRINT #fnum, data$

Description

Sends the string data$ over the TCP connection #fnum, automatically appending $CRLF (carriage return + line feed). This is a convenience wrapper around TCP SEND for text protocols (HTTP, SMTP, POP3, etc.). Internally calls TCP SEND with the string + CRLF appended.

Examples

TCP PRINT #1, "GET / HTTP/1.0"
TCP PRINT #1, "Host: example.com"
TCP PRINT #1, ""

Assembler Output

; TCP PRINT appends CRLF and calls send()
mov edx, 1
lea rcx, [data_str]
call __pb_tcp_print
; internally: concat data$ + $CRLF, then send()

See Also

  • TCP SEND
  • TCP LINE INPUT


UDP OPEN - PBXA64 Compiler Help

UDP OPEN

Opens a UDP socket for datagram communication.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

UDP OPEN "host:port" AS #fnum

Description

Creates a UDP socket associated with the specified remote host and port. Unlike TCP, UDP is connectionless — this statement creates the socket and stores the target address for subsequent UDP SEND operations. Internally creates a Winsock UDP socket (SOCK_DGRAM) and resolves the hostname via getaddrinfo.

Examples

UDP OPEN "192.168.1.100:12345" AS #1

Assembler Output

; UDP OPEN creates a DGRAM socket
lea rcx, [host_port_str]
mov edx, 1
call __pb_udp_open
; internally: socket(AF_INET, SOCK_DGRAM, 0)

See Also

  • UDP SEND
  • UDP RECV


UDP CLOSE - PBXA64 Compiler Help

UDP CLOSE

Closes a UDP socket and releases associated resources.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

UDP CLOSE #fnum

Description

UDP CLOSE closes a UDP socket previously opened with UDP OPEN. The specified file number #fnum is released for reuse. Internally calls closesocket() to close the Winsock socket descriptor. After closing, any further operations on #fnum will produce a runtime error unless the socket is re-opened.

Examples

UDP OPEN "192.168.1.1:9000" AS #1
UDP SEND #1, "data"
UDP CLOSE #1

Assembler Output

; UDP CLOSE
 mov ecx, dword ptr [fnum]
 call __pb_udp_close
; internally: closesocket(sock)

See Also

  • UDP OPEN
  • UDP SEND
  • UDP RECV
  • Back to command index


UDP SEND - PBXA64 Compiler Help

UDP SEND

Sends a UDP datagram to a specified destination.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

UDP SEND #fnum, data$ [, to$]

Description

Sends a UDP datagram containing data$ through the socket #fnum. If to$ is specified (in "host:port" format), the datagram is sent to that address; otherwise it is sent to the address specified in UDP OPEN. Internally calls Winsock sendto.

Examples

UDP SEND #1, "Hello"           ' to default target
UDP SEND #1, "Ping", "10.0.0.5:9999"

Assembler Output

; UDP SEND calls sendto()
mov edx, 1
lea rcx, [data_buffer]
mov r8d, [data_length]
call __pb_udp_send
; internally: sendto(socket, buf, len, 0, &addr, addrlen)

See Also

  • UDP RECV
  • UDP OPEN


UDP RECV - PBXA64 Compiler Help

UDP RECV

Receives a UDP datagram.

Kind: Statement | Category: Networking

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

UDP RECV #fnum, n TO var$

Description

Receives a UDP datagram of up to n bytes from the socket #fnum and stores it in var$. If no datagram is available, the call blocks until one arrives (UDP is connectionless, so each RECV retrieves a single datagram). Internally calls Winsock recvfrom.

Examples

LOCAL pkt$ AS STRING
UDP RECV #1, 1500 TO pkt$
MSGBOX "Datagram: " + pkt$

Assembler Output

; UDP RECV calls recvfrom()
mov edx, 1
mov r8d, 1500      ; max datagram size
lea r9d, [buffer]
call __pb_udp_recv
; result stored in PB_STRING64 descriptor

See Also

  • UDP SEND


#INCLUDE - PBXA64 Compiler Help

#INCLUDE

Includes the contents of another source file at compile time.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#INCLUDE "filename"
#INCLUDE ONCE "filename"

Description

#INCLUDE inserts the contents of the specified source file at the point of the directive during compilation. The included file is processed as if it were part of the original source. With #INCLUDE ONCE, the file is included only the first time the directive is encountered; subsequent #INCLUDE ONCE directives for the same file are ignored. This prevents duplicate declarations when the same include file is referenced from multiple places. The compiler searches for the file in the current directory and the include path.

Parameters

filename — path to the source file to include.

Parameters

Parameter | Description
filename | Source file path. Quoted string.

Examples

#INCLUDE "constants.inc"
#INCLUDE ONCE "windows.inc"
#INCLUDE "..\shared\utils.bi"

Assembler Output

; #INCLUDE is a compile-time directive.
; No code is generated for the directive itself.
; The included file's contents are compiled as part of
; the current compilation unit.

See Also

  • #COMPILE
  • #IF / #ENDIF
  • #DIM ALL


#COMPILE - PBXA64 Compiler Help

#COMPILE

Sets the output type of the compiled program.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#COMPILE EXE "outfilename"
#COMPILE DLL "outfilename"

Description

#COMPILE specifies the output file type and name for the compiled program. #COMPILE EXE produces a console or GUI executable (PE32+ format). #COMPILE DLL produces a dynamic-link library with export support. The output file name is specified as a quoted string. Only one #COMPILE directive should appear in a source file. The compiler uses this directive to determine the PE subsystem (console or GUI) and the output file format.

Parameters

outfilename — path for the output executable or DLL.

Parameters

Parameter | Description
outfilename | Output file path (quoted string).

Examples

#COMPILE EXE "MyProgram.exe"
#COMPILE DLL "MyLibrary.dll"

Assembler Output

; #COMPILE is a compile-time directive.
; It sets the PE header subsystem and output file name.
; No runtime code is generated.

See Also

  • #INCLUDE
  • #OPTIMIZE
  • #STACK
  • #DIM ALL


#DIM ALL - PBXA64 Compiler Help

#DIM ALL

Forces explicit declaration of all variables in the program.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#DIM ALL

Description

#DIM ALL requires that every variable be explicitly declared with LOCAL, GLOBAL, STATIC, SHARED, THREADED, or DIM before use. If #DIM ALL is in effect and the compiler encounters an undeclared variable, a compile-time error is generated. This directive helps catch typographical errors where a variable name is misspelled, which would otherwise silently create a new variable. #DIM ALL should be placed at the top of the source file, before any variable declarations or code.

Examples

#DIM ALL

FUNCTION Main()
  LOCAL x AS LONG
  x = 42               ' OK - declared
  ' y = 10             ' ERROR - y not declared
END FUNCTION

Assembler Output

; #DIM ALL is a compile-time directive.
; No runtime code is generated.

See Also

  • LOCAL
  • GLOBAL
  • DIM
  • #INCLUDE


#OPTIMIZE - PBXA64 Compiler Help

#OPTIMIZE

Sets the optimization level for code generation.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#OPTIMIZE level

Description

#OPTIMIZE controls the optimization level used during code generation. Higher levels enable more aggressive optimizations that produce faster or smaller code but may increase compile time. Level 0 disables optimization (fastest compilation). Level 1 enables basic peephole optimizations. Level 2 enables more advanced optimizations including constant folding, dead code elimination, and register allocation improvements. The default optimization level is 1.

Parameters

level — optimization level (0, 1, or 2).

Parameters

Level | Description
0 | No optimization, fastest compile.
1 | Basic optimizations (default).
2 | Full optimizations (best code).

Examples

#OPTIMIZE 2
' maximum optimization for release builds

Assembler Output

; #OPTIMIZE is a compile-time directive.
; It affects the code generator's optimization passes.
; No runtime code is generated directly.

See Also

  • #DEBUG
  • #STACK
  • #COMPILE


#STACK - PBXA64 Compiler Help

#STACK

Sets the stack reserve size for the compiled executable.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#STACK size

Description

#STACK sets the stack reserve size in the PE header of the compiled executable. The value specifies the number of bytes to reserve for the thread's stack. If the stack usage exceeds the reserve size, the stack is automatically extended (up to the commit size). The default stack size is 1 MB (1048576 bytes). Programs with deep recursion or large LOCAL variable allocations may need a larger stack. Programs with simple call trees may reduce the stack to save memory.

Parameters

size — stack reserve size in bytes.

Parameters

Parameter | Description
size | Stack reserve size in bytes.

Examples

#STACK 4194304     ' 4 MB stack for deep recursion
#STACK 262144      ' 256 KB stack for small programs

Assembler Output

; #STACK is a compile-time PE header directive.
; It sets the SizeOfStackReserve field in the PE header.
; No runtime code is generated.

See Also

  • #OPTIMIZE
  • #COMPILE
  • #ALIGN


#ALIGN - PBXA64 Compiler Help

#ALIGN

Sets member alignment for TYPE and UNION declarations.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

#ALIGN {NATURAL | 1 | 2 | 4 | 8 | 16}

Description

#ALIGN controls how structure members are aligned in memory within TYPE and UNION declarations. #ALIGN NATURAL aligns each member to its natural boundary (e.g. LONG to 4 bytes, QUAD to 8 bytes). Explicit numeric values force the specified alignment boundary (or smaller). The default alignment is #ALIGN NATURAL. This directive affects only TYPE/UNION layouts that follow it, not the current program stack frame.

Examples

#ALIGN 1
TYPE MyType
  b AS BYTE            ' offset 0
  l AS LONG            ' offset 1 (packed)
END TYPE

#ALIGN NATURAL
TYPE MyType2
  b AS BYTE            ' offset 0
  l AS LONG            ' offset 4 (aligned)
END TYPE

Assembler Output

; #ALIGN is a compile-time directive, no runtime code generated.
; TYPE layout calculated at compile time:
; #ALIGN 1: offsetof(l) = 1
; #ALIGN NATURAL: offsetof(l) = 4

See Also

  • #STACK
  • #OPTIMIZE
  • Back to command index


#DEBUG - PBXA64 Compiler Help

#DEBUG

Enables runtime error checking and debugging support.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

#DEBUG {NONE | ERROR | ALL}

Description

#DEBUG controls the level of runtime error checking code generated by the compiler. #DEBUG NONE disables all runtime checks — fastest execution but no protection against null pointers, division by zero, array bounds violations, or other runtime errors. #DEBUG ERROR enables runtime error checking (array bounds, null references, division by zero) but omits debugger integration. #DEBUG ALL enables full runtime checking plus debugger support (source-level debugging). The directive affects code generation from its point of appearance forward.

Examples

#DEBUG ALL
' ... debug-enabled code section ...
#DEBUG NONE
' ... optimized code section without checks ...

Assembler Output

; #DEBUG ERROR adds runtime guards:
; Array bounds check example:
 mov eax, dword ptr [index]
 cmp eax, dword ptr [array_ubound]
 ja __pb_error_subscript
; Division by zero guard:
 test ecx, ecx
 jz __pb_error_divzero

See Also

  • #OPTIMIZE
  • ON ERROR
  • Back to command index


#ASM / #ENDASM - PBXA64 Compiler Help

#ASM / #ENDASM

Inline assembly block for inserting raw x64 machine code.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#ASM
  ; x64 assembly instructions
  mov rax, rcx
  add rax, rdx
#ENDASM

Description

#ASM ... #ENDASM provides inline assembly capabilities, allowing raw x64 assembly instructions to be inserted directly into the compiled code. Assembly instructions are assembled by the built-in assembler and inserted at the current code location. The inline assembly block has access to all x64 registers and can reference PB variables by name. The compiler translates variable references to the appropriate RBP-relative or RIP-relative addressing modes. Standard x64 calling conventions apply.

Examples

FUNCTION AddInline(BYVAL a AS LONG, BYVAL b AS LONG) AS LONG
  #ASM
    mov eax, ecx     ; a is in ECX
    add eax, edx     ; b is in EDX
  #ENDASM
END FUNCTION

Assembler Output

; The inline assembly is assembled directly:
; mov eax, ecx  ->  89 C8
; add eax, edx  ->  01 D0
; These bytes are inserted directly into the code stream.

See Also

  • #CCODE
  • #PCODE
  • #OVERRIDE


#CCODE / #ENDC - PBXA64 Compiler Help

#CCODE / #ENDC

Inline C language block compiled by the integrated C compiler.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#CCODE
  /* C code here */
  int result = a + b;
#ENDC

Description

#CCODE ... #ENDC allows C language code to be embedded inline within PBXA64 source. The C code is compiled by the integrated C compiler and the resulting machine code is inserted at the current location. PB variables can be referenced using %var syntax for variable substitution. The C compiler handles type conversion between PB types and C types automatically. This is useful for performance-critical sections or for leveraging existing C algorithms.

Variable Substitution

Use %varname to reference PB variables within the C code block.

Examples

LOCAL a AS LONG, b AS LONG, r AS LONG
a = 10: b = 20
#CCODE
  int x = %a;
  int y = %b;
  int z = x * y + (x << 2);
  %r = z;
#ENDC
PRINT r

Assembler Output

; The C code is compiled and the resulting machine code
; is inserted directly into the PBXA64 code stream.
; Variable substitutions are replaced with actual addresses:
; mov eax, [rbp-8]     ; %a
; mov ecx, [rbp-16]    ; %b
; imul eax, ecx
; etc.

See Also

  • #ASM
  • #PCODE
  • #OVERRIDE


#PCODE / #ENDP - PBXA64 Compiler Help

#PCODE / #ENDP

Inline PILOT language block.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#PCODE
  A:Hello, PILOT!
  T:Hello, World!
#ENDP

Description

#PCODE ... #ENDP provides inline PILOT (Programmed Inquiry, Learning Or Teaching) language blocks. PILOT is an educational language with single-letter commands: A — Accept input, C — Compute/condition, E — End, J — Jump to label, M — Match input, N — No match, R — Remark, T — Type/display text, U — Use subroutine, Y — Yes/match. The PILOT block is compiled by the integrated PILOT translator and converted to PBXA64 code.

Commands

A: — Accept input from user.
C: — Conditional expression.
E: — End of program.
J: — Jump to label.
M: — Match input against pattern.
N: — No-match handler.
R: — Remark/comment.
T: — Type (display) text.
U: — Use subroutine.
Y: — Yes/match handler.

Examples

#PCODE
  R:This is a PILOT example
  T:Enter your name:
  A:
  T:Hello, N:
#ENDP

Assembler Output

; PILOT commands are translated to equivalent PBXA64 code.
; T: becomes PRINT statements
; A: becomes INPUT statements
; The resulting PBXA64 code is then compiled to x64.

See Also

  • #ASM
  • #CCODE
  • #OVERRIDE


#OVERRIDE - PBXA64 Compiler Help

#OVERRIDE

Replaces built-in functions with user-defined implementations.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#OVERRIDE builtinName$
  FUNCTION name(params) AS type
    ' custom implementation
  END FUNCTION
' ... more overrides ...
#END OVERRIDE

Description

#OVERRIDE allows replacing built-in PBXA64 functions with user-defined implementations. The builtinName$ specifies the name of the built-in function to override (with the $ suffix indicating it is a string type name). After the #OVERRIDE directive, one or more FUNCTION definitions provide custom implementations. The compiler redirects calls to the original built-in to the user-defined function instead. This is useful for customizing string manipulation, math functions, or I/O behavior.

Parameters

builtinName$ — name of the built-in function to override.
FUNCTION ... END FUNCTION — replacement implementation.

Parameters

Parameter | Description
builtinName$ | Built-in function name to override (string-typed).
name | User-defined replacement function.

Examples

#OVERRIDE UCASE$
  FUNCTION MyUcase(s AS STRING) AS STRING
    ' custom uppercase implementation
    FUNCTION = s  ' no-op override
  END FUNCTION

Assembler Output

; The compiler redirects calls to the overridden built-in
; to the user-provided function address instead of the
; runtime library address.
; call MyUcase         ; instead of call __pb_ucase

See Also

  • #ASM
  • #CCODE
  • #PCODE


#IF / #ELSEIF / #ELSE / #ENDIF - PBXA64 Compiler Help

#IF / #ELSEIF / #ELSE / #ENDIF

Conditional compilation directives.

Kind: Directive | Category: Compiler Directives

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

#IF expr
  ' code compiled if expr is true
#ELSEIF expr2
  ' code compiled if expr is false and expr2 is true
#ELSE
  ' code compiled if all conditions are false
#ENDIF

Description

#IF, #ELSEIF, #ELSE, and #ENDIF provide conditional compilation. Expressions are evaluated at compile time using compile-time constants (#DEFINE, CONST, ENUM values). Only the code block corresponding to the first true condition is compiled; all other blocks are skipped. The expression can use integer constants, comparison operators, and logical operators. #IF is useful for platform-specific code, debug vs. release builds, or feature toggles.

Parameters

expr — constant integer expression evaluated at compile time.

Parameters

Parameter | Description
expr | Compile-time constant expression (non-zero = true).

Examples

#IF %DEF(DEBUG)
  PRINT "Debug mode"
#ELSE
  PRINT "Release mode"
#ENDIF

#IF TARGET = 1
  #INCLUDE "win32.inc"
#ELSEIF TARGET = 2
  #INCLUDE "win64.inc"
#ENDIF

Assembler Output

; Conditional compilation is resolved at compile time.
; Only the selected code block is compiled.
; No runtime branch or conditional code is generated.

See Also

  • #INCLUDE
  • #COMPILE
  • CONST


SLEEP - PBXA64 Compiler Help

SLEEP

Suspends execution of the current thread for a specified number of milliseconds.

Kind: Statement | Category: Miscellaneous

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SLEEP millis

Description

SLEEP pauses the current thread's execution for the specified number of milliseconds. During the sleep period, the thread yields the remainder of its time slice to other threads. The actual delay may be slightly longer than requested due to system timer resolution (typically 1-16 ms). The runtime helper calls the Windows Sleep API. A value of 0 yields the current time slice to any ready thread. SLEEP is useful for polling loops, timing delays, and reducing CPU usage.

Parameters

millis — number of milliseconds to sleep.

Parameters

Parameter | Description
millis | Sleep duration in milliseconds (DWORD).

Examples

SLEEP 1000      ' pause for 1 second
SLEEP 10        ' pause for 10 ms
SLEEP 0         ' yield time slice

Assembler Output

; PBXA64 x64 assembly for SLEEP
mov ecx, [rbp-8]           ; milliseconds
call __imp_Sleep            ; Windows Sleep API

See Also

  • BEEP


SHELL - PBXA64 Compiler Help

SHELL

Executes an external program or command.

Kind: Statement | Category: Miscellaneous

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SHELL command$

Description

SHELL executes an external command or program as a subprocess. The command string can include arguments. The runtime helper calls the Windows system() function (MSVC CRT) or WinExec to execute the command. The shell returns when the child process terminates. SHELL waits for the child process to complete before continuing. The command can be any executable file, batch file, or command that can be executed from the command prompt.

Parameters

command$ — string containing the command line to execute.

Parameters

Parameter | Description
command$ | Command line string to execute.

Examples

SHELL "notepad.exe"
SHELL "dir /b > files.txt"
SHELL "cmd.exe /c pause"

Assembler Output

; PBXA64 x64 assembly for SHELL
lea rcx, [rbp-32]           ; PB_STRING64 descriptor (command)
call __pb_shell              ; calls system(string_data)
; Internal: system(str_data) via MSVC CRT

See Also

  • SLEEP
  • PRINT


RANDOMIZE - PBXA64 Compiler Help

RANDOMIZE

Seeds the pseudo-random number generator used by RND.

Kind: Statement | Category: Miscellaneous

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

RANDOMIZE [seed]

Description

RANDOMIZE initializes the pseudo-random number generator with a seed value. If seed is provided, that value is used. If omitted, the runtime helper obtains a seed from GetTickCount64 (milliseconds since system start) to ensure different sequences on each run. Using the same seed value produces the same sequence of random numbers from RND, which is useful for debugging or reproducible simulations.

Parameters

seed — optional numeric seed value for the RNG.

Parameters

Parameter | Description
seed | Optional seed (LONG). Omit for time-based seeding.

Examples

RANDOMIZE          ' seed from system timer
RANDOMIZE 42       ' seed with fixed value for reproducibility

Assembler Output

; PBXA64 x64 assembly for RANDOMIZE with seed
mov ecx, [rbp-8]           ; seed value
call __pb_randomize         ; calls srand(seed)

; RANDOMIZE without seed:
call __imp_GetTickCount64   ; get system time as seed
mov ecx, eax
call __pb_randomize

See Also

  • RND
  • RANDOM


SWAP - PBXA64 Compiler Help

SWAP

Exchanges the values of two variables.

Kind: Statement | Category: Miscellaneous

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

SWAP var1, var2

Description

SWAP exchanges the values of two variables. Both variables must be of the same data type. SWAP is implemented as a temporary copy: the value of var1 is saved to a temporary location, var2 is copied to var1, and the temporary is copied to var2. For simple numeric types, the compiler may use XCHG or push/pop sequences. For string descriptors and UDTs, the entire memory block is swapped via CopyMemory or push/pop of the descriptor structure.

Parameters

var1 — first variable.
var2 — second variable (same type as var1).

Parameters

Parameter | Description
var1 | First variable to swap.
var2 | Second variable to swap (same type as var1).

Examples

LOCAL a AS LONG, b AS LONG
a = 1: b = 2
SWAP a, b
PRINT a, b     ' prints 2, 1

Assembler Output

; PBXA64 x64 assembly for SWAP (LONG)
mov eax, [rbp-8]           ; load var1
mov ecx, [rbp-16]          ; load var2
mov [rbp-16], eax          ; var2 = var1
mov [rbp-8], ecx           ; var1 = var2

; SWAP for STRING descriptors (32 bytes):
; CopyMemory(addr1, addr2, 32) via push/pop sequence

See Also

  • INCR/DECR
  • MOV


INCR/DECR - PBXA64 Compiler Help

INCR / DECR

Increments or decrements a numeric variable.

Kind: Statement | Category: Miscellaneous

PBXA64 Status: IMPLEMENTED

PBXA64 Certification: [CERTIFIED TESTED]

Syntax

INCR var [, amount]
DECR var [, amount]

Description

INCR adds an amount to a numeric variable (default: 1). DECR subtracts an amount from a numeric variable (default: 1). These compound assignment operators are optimized to a single ADD or SUB instruction in the generated code. The variable can be of any numeric type. If amount is negative, the operation effectively reverses (INCR with negative amount is equivalent to DECR).

Parameters

var — numeric variable to modify.
amount — optional amount to add/subtract (default: 1).

Parameters

Parameter | Description
var | Numeric variable to increment or decrement.
amount | Optional amount (defaults to 1).

Examples

LOCAL x AS LONG
x = 10
INCR x             ' x = 11
INCR x, 5          ' x = 16
DECR x             ' x = 15
DECR x, 3          ' x = 12

Assembler Output

; PBXA64 x64 assembly for INCR
add dword [rbp-8], 1       ; x += 1

; INCR x, 5
add dword [rbp-8], 5       ; x += 5

; DECR x
sub dword [rbp-8], 1       ; x -= 1

; DECR x, 3
sub dword [rbp-8], 3       ; x -= 3

See Also

  • SWAP
  • LOCAL


PILOT A: - PBXA64 Compiler Help

PILOT A: (Accept)

Accepts keyboard input and stores it in a variable.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

A:$var

Description

The A: command reads a line of text from the keyboard and assigns it to the specified variable $var. The variable must be a string variable. Execution pauses until the user presses Enter. The newline is stripped before assignment.

Examples

R:PILOT program with input
T:Enter your name:
A:$name
T:Hello, $name!

Assembler Output

; A:$name calls runtime line input
sub rsp, 40
lea rcx, [name_descriptor]
call __pb_pilot_accept
add rsp, 40

See Also

  • PILOT T: (Type)
  • PILOT C: (Compute)


PILOT C: - PBXA64 Compiler Help

PILOT C: (Compute)

Evaluates an expression and assigns the result to a variable.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

C:var = expr

Description

The C: command evaluates an arithmetic or string expression and stores the result in the named variable. The variable can be numeric or string. Standard arithmetic operators (+, -, *, /) and string concatenation are supported. This is the general-purpose computation command in PILOT.

Examples

C:counter = counter + 1
C:result = a * b + c
C:fullname = first + " " + last

Assembler Output

; C:result = a + b
mov eax, dword ptr [a]
add eax, dword ptr [b]
mov dword ptr [result], eax

See Also

  • PILOT A: (Accept)
  • PILOT T: (Type)


PILOT E: - PBXA64 Compiler Help

PILOT E: (End)

Terminates the PILOT program.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

E:

Description

The E: command marks the end of the PILOT program. Execution stops at this point. Any code after E: is unreachable unless reached via a J: jump. If E: is omitted, execution falls through to the end of the #PCODE block.

Examples

R:Simple PILOT program
T:Hello, world!
E:

Assembler Output

; E: generates ret
add rsp, 40
ret

See Also

  • PILOT J: (Jump)


PILOT J: - PBXA64 Compiler Help

PILOT J: (Jump)

Unconditional jump to a named label.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

J:*label

Description

The J: command transfers control unconditionally to the line marked with *label. Labels must start with * and appear at the beginning of a PILOT line. Forward and backward jumps are both supported.

Examples

R:Count to 5
C:i = 1
*loop
T:#$i
C:i = i + 1
J:*loop

Assembler Output

; J:*loop generates jmp
jmp label_loop

See Also

  • PILOT E: (End)
  • PILOT U: (Use)


PILOT M: - PBXA64 Compiler Help

PILOT M: (Match)

Performs pattern matching against the accept buffer and sets the YES/NO condition flag.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

M:pattern

Description

The M: command matches the previously accepted input (from A:) against a pattern. The pattern may contain literal text and wildcards. If the match succeeds, the YES condition is set; otherwise the NO condition is set. The subsequent Y: or N: command reflects the result. The match buffer is stored internally and updated by each A: command.

Examples

T:Enter yes or no:
A:$answer
M:yes
Y:T:You said yes
N:T:You said no

Assembler Output

; M:pattern - calls runtime pattern matcher
lea rcx, [match_pattern]
call __pb_pilot_match
mov byte ptr [yesno_flag], al

See Also

  • PILOT Y: (Yes)
  • PILOT N: (No)
  • PILOT A: (Accept)


PILOT N: - PBXA64 Compiler Help

PILOT N: (No)

Executes the following command if the previous match failed.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

N:

Description

The N: command checks the YES/NO condition flag set by the most recent M: command. If the match failed (NO), the command on the following line (or on the same line after the colon) is executed. If the match succeeded (YES), the next line is skipped. This is the negative conditional branch in PILOT.

Examples

M:apple
Y:T:It's an apple
N:T:It's not an apple

Assembler Output

; N: - conditional skip on NO
cmp byte ptr [yesno_flag], 0
jne skip_no
; following command executes only if match failed
skip_no:

See Also

  • PILOT Y: (Yes)
  • PILOT M: (Match)


PILOT R: - PBXA64 Compiler Help

PILOT R: (Remark)

Comment or remark — ignored by the compiler.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

R:text

Description

The R: command is a comment line. Everything after R: up to the end of the line is ignored by the compiler. R: lines are useful for documentation and code annotations.

Examples

R:This is a PILOT comment
R:This program greets the user
T:Hello!

Assembler Output

; R: generates no code

See Also

  • (none)


PILOT T: - PBXA64 Compiler Help

PILOT T: (Type)

Prints text to the console.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

T:text

Description

The T: command outputs text to the standard output. Variable substitution is supported — any variable name prefixed with $ in the text is replaced with its current value. For a literal $, use $$.

Examples

T:Hello, world!
T:The value is $result

Assembler Output

; T:text calls __pb_print_cstr
lea rcx, [literal_string]
call __pb_print_cstr

See Also

  • PILOT A: (Accept)
  • PILOT Y: (Yes)


PILOT U: - PBXA64 Compiler Help

PILOT U: (Use)

Conditionally executes a labelled section.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

U:label

Description

The U: command (Use) combines a match check with execution. If the previous M: command succeeded (YES condition is true), execution jumps to the named *label. If the match failed, control passes to the next line. This is equivalent to Y: followed by J:*label but more concise.

Examples

M:hello
U:*greet
T:Not recognized
E:

*greet
T:Hello to you too!
E:

Assembler Output

; U:label - conditional jump on YES
cmp byte ptr [yesno_flag], 1
jne skip_use
jmp use_label
skip_use:

See Also

  • PILOT Y: (Yes)
  • PILOT N: (No)
  • PILOT J: (Jump)


PILOT Y: - PBXA64 Compiler Help

PILOT Y: (Yes)

Executes the following command if the previous match succeeded.

Kind: Statement | Category: PILOT Frontend (#PCODE)

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Syntax

Y:

Description

The Y: command checks the YES/NO condition flag set by the most recent M: command. If the match succeeded (YES), the command on the following line (or after the colon) is executed. If the match failed (NO), the next line is skipped. This is the positive conditional branch in PILOT, complementing N:.

Examples

M:42
Y:T:The answer is 42
N:T:Wrong answer

Assembler Output

; Y: - conditional skip on YES
cmp byte ptr [yesno_flag], 1
jne skip_yes
; following command executes only if match succeeded
skip_yes:

See Also

  • PILOT N: (No)
  • PILOT M: (Match)


Cross-Frontend Interchange Overview - PBXA64 Compiler Help

Cross-Frontend Interchange Overview

PBXA64 supports mixing multiple programming frontends within a single source file or project. This feature allows developers to leverage the strengths of each language — PowerBASIC's ease of use, C's system-level access, PILOT's educational simplicity, and raw assembler for performance-critical sections.

Kind: Narrative | Category: Cross-Frontend Interchange

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Available Frontends

Frontend | Directive | Description
PowerBASIC (PB) | Default | Full-featured BASIC dialect — variables, control flow, DDT GUI, file I/O, strings
C | #CCODE | Inline C with access to PB variables via %varname syntax
PILOT | #PCODE | Educational PILOT language — single-letter commands, pattern matching
Inline ASM | #ASM | x86-64 assembler with full register access and stack offsets

Compilation Pipeline

All frontends compile through the same intermediate representation (IR). Each frontend's parser generates IR nodes that are fed into a unified optimizer and code generator. This means:

  • Variables declared in PB are visible to C and ASM blocks
  • Functions defined in any frontend can be called from any other frontend
  • The calling convention is unified across all frontends (Microsoft x64)
  • All frontends share the same runtime library

Frontend Selection

The default frontend is PowerBASIC. To switch frontends, use the directives #CCODE, #PCODE, or #ASM. To return to PowerBASIC, use #PBCODE.

#PCODE
T:Hello from PILOT
#CCODE
int x = 42;
#ASM
mov eax, 42
#PBCODE
PRINT "Back in PB"

See Also

  • Variables Between Frontends
  • Calling Between Frontends


Variables Between Frontends - PBXA64 Compiler Help

Variables Between Frontends

PBXA64's unified variable model allows variables declared in one frontend to be accessed from any other frontend, enabling seamless data sharing without marshalling.

Kind: Narrative | Category: Cross-Frontend Interchange

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

PB to C Variable Access

Variables declared in PB (LOCAL or GLOBAL) can be read and written from inline C blocks using the %varname prefix. The compiler resolves the variable to its stack offset or global address.

LOCAL x AS LONG
x = 10
#CCODE
%x = %x * 2;   ' x is now 20

PB to ASM Variable Access

From inline ASM, PB local variables are accessed via RBP-relative offsets. Global variables are accessed by name (the compiler emits the symbol address).

LOCAL x AS LONG    ' typically at [rbp-8]
LOCAL y AS QUAD    ' typically at [rbp-16]
#ASM
mov eax, [rbp-8]   ; load x
add eax, 10
mov [rbp-8], eax   ; store x
; global access (declared as GLOBAL g AS LONG)
mov eax, [g]       ; load global g

String Variables

PB STRING variables are PB_STRING64 descriptors. From ASM, the descriptor layout is:

struct PB_STRING64 {
    char *data;     ; offset 0: pointer to string data
    int64 len;      ; offset 8: string length
    int64 capacity; ; offset 16: allocated capacity
};
LOCAL s AS STRING
#ASM
mov rcx, [rbp-24]   ; s.data (address of string content)
mov rdx, [rbp-16]   ; s.len   (length in bytes)

C to PB Variable Access

From inline C, PB variables use the same %varname syntax. The C frontend maps these to the appropriate memory locations:

LOCAL counter AS LONG
#CCODE
for (int i = 0; i < 10; i++) {
    %counter += i;
}

See Also

  • Cross-Frontend Interchange Overview
  • Calling Between Frontends


Calling Between Frontends - PBXA64 Compiler Help

Calling Between Frontends

Functions and subroutines defined in any frontend can be called from any other frontend. The IR bridge unifies the Microsoft x64 calling convention across all frontends.

Kind: Narrative | Category: Cross-Frontend Interchange

PBXA64 Status: IMPLEMENTED

Certification: [CERTIFIED TESTED]

Calling C Functions from PB

Functions defined in a #CCODE block can be called from PB using the standard CALL statement. The compiler knows the function's signature from the C declaration.

#CCODE
int add(int a, int b) {
    return a + b;
}
#PBCODE
LOCAL result AS LONG
CALL add(10, 20) TO result
PRINT result    ' 30

Calling PB Functions from C

PB FUNCTIONS and SUBs are directly callable from inline C blocks using standard C function call syntax.

FUNCTION Multiply(BYVAL a AS LONG, BYVAL b AS LONG) AS LONG
    FUNCTION = a * b
END FUNCTION
#CCODE
int r = Multiply(6, 7);   ' r = 42

Calling PB Routines from ASM

From inline ASM, PB routines are called by name using the standard x64 calling convention (RCX, RDX, R8, R9 for first 4 arguments).

FUNCTION Square(BYVAL n AS LONG) AS LONG
    FUNCTION = n * n
END FUNCTION
#ASM
mov ecx, 5       ; first argument
sub rsp, 40      ; shadow space
call Square
add rsp, 40
; eax now contains 25

Calling C from ASM

C functions are also called via standard x64 convention:

#CCODE
int triple(int x) { return x * 3; }
#ASM
mov ecx, 7
sub rsp, 40
call triple
add rsp, 40
; eax = 21

Important Notes

  • The Microsoft x64 calling convention applies: RCX, RDX, R8, R9 for integer arguments, XMM0-XMM3 for floating-point
  • The caller must allocate 32 bytes of shadow space before calling a function
  • Functions must preserve RBX, RBP, RDI, RSI, R12-R15, and XMM6-XMM15
  • The return value is in RAX (integer) or XMM0 (floating-point)

See Also

  • Cross-Frontend Interchange Overview
  • Variables Between Frontends