Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> System Calls

PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC - the scope of the language as well as it's specific capabilities.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • System Functions
    PowerBASIC supports a variety of functions which generally get/set information from Windows (clipboard, desktop, memory, etc.) or from the application itself. These can be broken into the following categories.

       Get Text, Set Text, Get Item,
       Set Item, Reset 
      • Environment
       environ, environ$ 
      • Execute Other Programs  
      • Application Information
       command$, EXE 
      • DESKTOP
       Get Client, Get Loc, Get Size 
      • WINDOW
       Get ID, Get Parent 
      • Memory Access
       peek, peek$, poke, poke$ 
       alloc, free, lock, size, unlock 

    System Call Function Summary
    Here's a one-line description of each of the functions.

    • CLIPBOARD - get/set clipboard content (text and images)
    • command$ - get program command-line arguments
    • DESKTOP - get desktop size, client size, client top/left coordinates
    • environ/environ$ - set/return environment values
    • EXE - get application name/path
    • GLOBALMEM - Allocate or release global memory
    • peek/peek$ - get byte(s) at memory location
    • poke/poke$ - store byte(s) at memory location
    • shell - run external program w/option to wait until program completes
    • WINDOW - get parent/id of any window in application

    System Call Function Reference
    Here's a quick reference of the available functions, in alphabetical order.

          CLIPBOARD Set Text "mystring" TO iSuccess&
          CLIPBOARD Get Text TO RetreivedText$
          CLIPBOARD Set Item cbFormat, hItem TO iSuccess&
          CLIPBOARD Get Item cbFormat TO hReturn&
          CLIPBOARD RESET TO iSuccess      ' delete clipboard content
          iSuccess&:  0=false, -1=success
          hItem is handle of item sent to clipboard
          hReturn is handle of item received from clipboard
          cbFormats (clipboard formats):
          %CF_BITMAP - bitmap handle (HBITMAP)
          %CF_DIB - memory object (BITMAPINFO structure and bitmap bits)
          %CF_DIF - Software Arts' Data Interchange Format
          %CF_ENHMETAFILE - enhanced metafile handle (HENHMETAFILE)
          %CF_HDROP - HDROP handle (list of files)
          %CF_LOCALE - locale identifier handle
          %CF_METAFILEPICT - metafile picture handle (METAFILEPICT)
          %CF_OEMTEXT - OEM text characters (CRLF EOL, Null EOF)
          %CF_PALETTE - color palette handle
          %CF_PENDATA - MS Pen Computing data
          %CF_RIFF - RIFF audio data
          %CF_SYLK - MS Symbolic Link (SYLK) format
          %CF_TEXT - Text (CRLF EOL, Null EOF)
          %CF_TIFF - TIF file
          %CF_UNICODETEXT - Unicode text (CRLF EOL, Null EOF)
          %CF_WAVE - WAV audio data

      Clipboard holds only one type of data at a time. If you Set the clipboard, previous data is lost.

      With Get Item, hReturn& is the handle to the item retrieved.

    • command$
          result$ = command$       ' entire command-line
          result$ = command$(n%)   ' nth command-line argument, 0=all

      Assumes arguments are space delimited. If n% is too large, "" is returned.

      The IDE allows specification of a command-line string for testing purposes.

    • DESKTOP GET Client/Size/Loc
          DESKTOP Get Client TO Width&, Height&    'client height width
          DESKTOP Get Size TO Width&, Height&      'entire desktop size
          DESKTOP Get Loc TO x&, y&                'top/left corner

      Client area does not include taskbar. Client top/left is normally 0,0 but if taskbar is moved to top or left side of screen, then the client top/left changes accordingly.

    • environ
          ENVIRON "name=value"    'use string name/value pairs to set values
          ENVIRON "name="         'name only (no value) removes from table
          ENVIRON "temp=c:\temp"  'set "temp" environ value
          ENVIRON "path=c:\"      'don't try this! just an example.

    • environ$
          result$ = environ$("path")   'get path value from environment
          result$ = environ$("temp")   'get "temp" value from environment
          result$ = environ$(12)       'get 12th environment table entry

      When an app starts, it is given a copy of the system environment table. PowerBASIC functions work with the copy. When the program ends, the system environment table is unchanged.

    • EXE
          Assume this is run:   "c:\data\fixit.exe"
          result$ = EXE.extn$    ' ".exe"
          result$ = EXE.full$    ' "c:\data\fixit.exe"
          result$ =$    ' "fixit"
          result$ = EXE.namex$   ' "fixit.exe"
          result$ = EXE.path$    ' "c:\data\"

      If this code is in a DLL, the information returned is that of the EXE which loaded the DLL.

    • GLOBALMEM alloc/free/lock/size
          GLOBALMEN alloc   count   TO vHandle
          GLOBALMEN free    mHandle TO vHandle
          GLOBALMEN lock    mHandle TO vPointer
          GLOBALMEN size    mHandle TO vSize
          GLOBALMEN unlock  mHandle TO vLocked

    • peek/peek$
          Dim address As DWord      ' 32 bit address (4 bytes)
          ---Number Syntax:
          NumVar = PEEK, address         'assign 1 byte to numeric variable
          NumVar = PEEK BYTE, address    'read/convert # bytes corresponding
                                         'to specified data type 
                                         'can use byte, word, dword, 
                                         'integer, long, quad,
                                         'single, double, ext, cur, cux
          n% = PEEK Integer, address
          n! = PEEK Single, address
          ---String Syntax:
          StringVariable = PEEK ASCIIZ, address, ByteCount  
          s$ = PEEK$ address, 5        'get 5 characters, put into s$
          Dim s as ASCIIZ
          s = PEEK$ ASCIIZ address, 5  'get 5 characters, insert &Nul at end

      Use peek to get a single byte, and peek$ to return a sequence of bytes.

    • poke/poke$
          Dim address As DWord      ' 32 bit address (4 bytes)
          ---Number Syntax:
          poke address, i%          ' put value of i% at 1-byte address
          poke BYTE, address, i%    ' put # bytes corresponding to specified
                                    ' data type, starting at address
                                    ' can use byte, word, dword,
                                    ' integer, long, quad, single,
                                    ' double, ext, cur, cux
          ---String Syntax:
          poke$ String, address, "hello"   ' fixed-length or dynamic string
          poke$ ASCIIZ, address, "hello"   ' ASCIIZ string
          poke$ Field, address,  "hello"   ' Field string

      Use poke for numeric data, and poke$ for string data. These are generally used for speed-critical sections of a program, or to access memory (such as video memory) that otherwise would not be accessible using standard PowerBASIC functions.

      Poke$ will write all characters found in the string being written. The application must control the location and length of written data to ensure that the written data does not write into areas which can corrupt other data or create a GPF.

    • shell
          pID& = SHELL("notepad.exe",1)    'run notepad and keep going
          pID& = SHELL("cmd /c dir*.*")    'open DOS, run "dir *.*", end
          pID& = SHELL("cmd /k dir*.*")    'open DOS, run "dir *.*", not end
          pID& is the child process ID.
          Window Styles:
              0 - hide window
              1 - normal w/focus (default)
              2 - minimized w/focus
              3 - maximized w/focus
              4 - normal w/o focus
              5 - minimized w/o focus

      Runs another app without waiting for it to stop. ERR contains information on success/failure.

      Option available for child process to inherit file handles of current process. See PowerBASIC Help for more information.

      For more info on using the DOS CMD command, open a DOS window and enter "cmd /?". This gives a listing of all cmd options.

      Paths searched for program to execute: program directory, default directory, \windows\system32, \windows\system16, \windows, and PATH.

          WINDOW Get ID hWin TO ID&               ' hWin - handle of window
          WINDOW Get Parent hWin TO hParent&

      Works on control or dialog. ID& = control ID (or 0 if hWin is a dialog).

    If you have any suggestions or corrections, please let me know.