• Składnia instrukcji Declare

Aby użyć funkcji API w aplikacji MS Access, należy podać nazwę funkcji API i wskazać docelowe miejsce, gdzie się deklarowana procedura (funkcja) znajduje. Dane te podajemy w sekcji deklaracji modułu, posługując się instrukcją Declare. Słowo kluczowe Declare oznacza, że procedura (funkcja) znajduje się w zewnętrznej bibliotece i nie jest wbudowaną procedurą (funkcją) w bieżącej aplikacji.
Wywołania API mogą mieć postać funkcji lub procedury, podobnie jak procedury (funkcje) VBA w MS Access. Funkcja po wywołaniu zwraca wartość, a podprocedura nie zwraca żadnej wartości.

Składnia instrukcji Declare dla procedury.

[Public | Private] Declare [PtrSafe] Sub nazwa Lib "nazwa_biblioteki" [Alias "alias"][([lista_argumentów])]

Składnia instrukcji Declare dla funkcji

[Public | Private] Declare [PtrSafe] Function nazwa Lib "nazwa_biblioteki" [Alias "alias"][([lista_argumentów])] [As typ]

Składnia instrukcji Declare składa się z następujących elementów:

Argument lista_argumentów składa się z następujących elementów o poniższej składni:

[Optional] [ByVal | ByRef] [ParamArray] nazwa_zmiennej [( )] [As typ]

Użycie

W przypadku procedur typu Function, typ procedury ściśle określa typ zwracanych danych. Aby określić jawnie typ zwracanych przez funkcję danych, należy użyć klauzuli As następującej po liście lista_argumentów. Wewnątrz listy lista_argumentów klauzuli As można używać do określania typu każdego przekazywanego do procedury argumentu. Dodatkowo, oprócz możliwości określenia typów standardowych, można na liście lista_argumentów umieścić klauzulę As Any, co blokuje kontrolę zgodności typów i umożliwia przekazywanie do procedury danych dowolnego typu.

Puste nawiasy wskazują, że procedura typu Sub lub Function nie ma żadnych argumentów oraz że system Visual Basic powinien sprawdzać, czy faktycznie żaden argument nie jest przekazywany do procedury. W poniższym przykładzie, procedura MojaProcedura nie pobiera żadnych argumentów. Przy wywołaniu procedury MojaProcedura z dowolnym argumentem wystąpi błąd:

Declare Sub MojaProcedura Lib "Moja_biblioteka" ()

Jeżeli do deklaracji dołączona zostanie lista argumentów, przy każdym wywołaniu procedury sprawdzana jest liczba i typ argumentów. W poniższym przykładzie procedura MojaProcedura wymaga jednego argumentu typu Long:

Declare Sub MojaProcedura Lib "Moja_biblioteka" (X As Long)

Uwaga. Na liście lista_argumentów instrukcji Declare nie można umieszczać ciągów o stałej długości. Do procedur mogą być przekazywane jedynie ciągi o zmiennej długości. Ciągi o stałej długości mogą występować jako argumenty procedury, ale przed przekazaniem ich do procedury są zamieniane na ciągi o zmiennej długości.

Przy wywoływaniu procedur zewnętrznych wymagających ciągu o wartości zerowej, wykorzystywana jest stała vbNullString. Ciąg o wartości zerowej nie jest jednak tym samym co ciąg o długości zerowej ("").

W programie Microsoft Access można użyć instrukcji Declare na poziomie modułu w module standardowym, aby zadeklarować odwołanie do zewnętrznej procedury w bibliotece dołączanej dynamicznie (DLL). Domyślnie instrukcja Declare jest publiczna. Umieszczając instrukcję Declare w module klasy, należy ją poprzedzić słowem kluczowym Private.
W poniższym przykładzie najpierw deklarowana jest procedura z biblioteki DLL, a następnie może ona zostać wywołana z poziomu języka VBA w przykładowej procedurze UruchomAPI:

' W module standardowym
Declare Function timeGetTime Lib "winmm.dll" Alias "timeGetTime" () As Long
   ' lub
Public Declare Function timeGetTime Lib "winmm.dll" Alias "timeGetTime" () As Long
' _______________________________________________________________________
' a w module klasy
Private Declare Function timeGetTime Lib "winmm.dll" Alias "timeGetTime" () As Long
' _______________________________________________________________________

' przykładowe wywołanie:
Private Sub UruchomAPI()
Dim lngTime As Long
   lngTime = timeGetTime
   MsgBox lngTime
End Sub

Słownik użytych terminów.

• poziom modułu

Opisuje kod programu w sekcji deklaracji modułu. Dowolny kod programu występujący poza procedurą określany jest jako kod programu na poziomie modułu. Deklaracje muszą wystąpić jako pierwsze, po nich następują procedury.

• procedura

Opatrzona nazwą sekwencja instrukcji wykonywanych jako jeden blok. Przykładami procedur są Function, Property i Sub. Nazwa procedury jest zawsze definiowana na poziomie modułu. W procedurze musi zawierać się cały wykonywalny kod programu. Procedury nie mogą być zagnieżdżone w innych procedurach.

• słowo kluczowe

Słowo lub symbol rozpoznawany jako część języka programowania Visual Basic, na przykład instrukcja, nazwa funkcji lub operator.

• biblioteka dołączana dynamicznie (DLL)

Biblioteka procedur ładowana i dołączana do aplikacji w czasie wykonywania. Biblioteki DLL są tworzone w innych językach programowania, takich jak C, MASM lub FORTRAN.

• moduł

Zestaw deklaracji, po których następują procedury.

• deklaracja

Niewykonywalny kod programu określający nazwę stałej, zmiennej lub procedury i definiujący jej cechy, takie jak typ danych. Dla procedur z bibliotek DLL deklaracje określają nazwy, biblioteki i argumenty.

• wyrażenie

Kombinacja słów kluczowych, operatorów, zmiennych i stałych, która daje w wyniku ciąg znaków, liczbę lub obiekt. Wyrażenia mogą być używane do przeprowadzania obliczeń, wykonywania operacji na znakach lub testowania danych.

• zmienna

Opatrzone nazwą miejsce w pamięci do przechowywania danych, które mogą ulegać modyfikacjom w trakcie wykonywania programu. Każda zmienna zaopatrzona jest w unikatową nazwę, która identyfikuje ją w obrębie danego zakresu. Typ danych może być określony lub nie. Nazwy zmiennych muszą zaczynać się literą, muszą być unikatowe w obrębie swego zakresu, nie mogą być dłuższe niż 255 znaków i nie mogą zawierać kropki ani znaku deklarującego typ.

• stała

Element o nadanej nazwie, który zachowuje stałą wartość przez cały czas działania programu. Stała może być ciągiem znaków lub literałem numerycznym, inną stałą lub dowolną kombinacją zawierającą operatory arytmetyczne i logiczne, z wyjątkiem operatora Is oraz operatora potęgowania. Każda aplikacja główna może definiować własny zestaw stałych. Dodatkowe stałe mogą być definiowane przez użytkownika za pomocą instrukcji Const. Stałych można użyć w dowolnym miejscu kodu programu zamiast ich rzeczywistych wartości.

• zakres

Określa widoczność zmiennej, procedury lub obiektu. Na przykład, zmienna zadeklarowana jako Public jest widoczna dla wszystkich procedur we wszystkich modułach, o ile nie włączono opcji Private Module. Jeżeli opcja Private Module została włączona, dany moduł jest prywatny i w związku z tym nie jest widoczny dla projektów wskazujących go (odwołujących się doń). Zmienne zadeklarowane w danej procedurze są widoczne tylko w ramach tej procedury i, o ile nie zostaną zadeklarowane jako zmienne typu Static, tracą swoją wartość pomiędzy wywołaniami.

• argument

Stała, zmienna lub wyrażenie przekazywane do procedury.

•ByVal - przez wartość

Sposób przekazywania polegający na przekazaniu do procedury wartości argumentu zamiast jego adresu. Pozwala to procedurze na uzyskanie dostępu do kopii zmiennej. W rezultacie bieżąca wartość zmiennej nie może zostać zmodyfikowana przez procedurę, do której zmienna ta została przekazana.

• ByRef - przez odwołanie

Sposób przekazywania polegający na przekazaniu do procedury adresu argumentu zamiast wartości argumentu. Pozwala to procedurze na uzyskanie dostępu do faktycznej zmiennej. W rezultacie bieżąca wartość zmiennej może zostać zmodyfikowana przez procedurę, do której zmienna ta została przekazana. O ile nie zaznaczono inaczej, argumenty są przekazywane do procedur przez odwołanie.

• tablica

Zbiór kolejno indeksowanych elementów mających ten sam wewnętrzny typ danych. Każdy element tablicy posiada unikatowy numer indeksu. Przeprowadzenie zmian dla jednego elementu tablicy nie wpływa na inne jej elementy.

• typ danych

Cecha zmiennej określająca rodzaj danych, jaki ta zmienna może przechowywać. Typami danych są Byte, Boolean, Integer, Long, LongPtr, LongLong, Currency, Decimal, Single, Double, Date, String, Object i Variant (domyślny) oraz typy danych zdefiniowane przez użytkownika, jak również konkretne typy obiektów.

• typ danych Byte

Typ danych używany do przechowywania dodatnich liczb całkowitych z zakresu od 0 do 255. Zmienne typu Byte są przechowywane jako liczby 8-bitowe (1-bajtowe) pojedynczej precyzji, bez znaku.

• typ danych Boolean

Typ danych przyjmujący tylko dwie wartości: True (-1) lub False (0). Zmienne typu Boolean są przechowywane jako liczby 16-bitowe (2-bajtowe).

• typ danych Integer

Typ danych przechowujący zmienne całkowite jako 2-bajtowe liczby z zakresu od -32 768 do 32 767. Typ danych Integer jest także używany do przedstawiania wartości typu wyliczeniowego. W języku Visual Basic znakiem deklaracji typu odpowiadającym typowi Integer jest znak procent (%).

• typ danych Long

Typ danych służący do przechowywania liczb całkowitych na 4 bajtach, o zakresie wartości od -2 147 483 648 do 2 147 483 647. W języku Visual Basic znakiem deklaracji typu odpowiadającym typowi Long jest znak ampersand (&).

• typ danych LongPtr

Typ ten zalecany jest do przechowywania wskaźników i uchwytów, zarówno w środowisku 32-bitowym jak i 64-bitowym środowisku VBA7, co umożliwia pisanie przenośnego kodu, który można uruchomić w zarówno 32-bitowym i 64-bitowym środowisku. LongPtr nie jest prawdziwym typem danych. W środowisku 32-bitowym przyjmuje czterobajtowy typ Long, a w środowisku 64-bitowym przyjmuje ośmiobajtowy typ LongLong.
Zakres wartości: od -2 147 483 648 do 2 147 483 647 w 32-bitowym środowisku,
od -9 223 372 036 854 775 808 do 9 223 372 036 854 775 807 w 64-bitowym środowisku.

• typ danych LongLong

Typ danych służący do przechowywania liczb całkowitych na 8 bajtach, o zakresie wartości od -9 223 372 036 854 775 808 do 9 223 372 036 854 775 807. W języku VBA7 znakiem deklaracji typu odpowiadającym typowi LongLong jest znak daszek (^)

• typ danych Currency

Typ danych o zakresie od -922 337 203 685 477,5808 do 922 337 203 685 477,5807. Tego typu danych używa się do obliczeń dotyczących pieniędzy i do obliczeń stałoprzecinkowych, w przypadku których dokładność ma szczególne znaczenie. W języku Visual Basic znakiem deklaracji typu odpowiadającym typowi Currency jest znak @.

• typ danych Single

Typ danych przechowujący zmienne zmiennoprzecinkowe pojedynczej precyzji jako liczby 32-bitowe (2-bajtowe) z zakresu od –3,402823E38 do –1,401298E-45 dla liczb ujemnych i od 1,401298E-45 do 3,402823E38 dla liczb dodatnich. W języku Visual Basic znakiem deklaracji typu odpowiadającym typowi Single jest wykrzyknik (!).

• typ danych Double

Typ danych przechowujący liczby zmiennoprzecinkowe o podwójnej precyzji jako liczby 64-bitowe z zakresu od -1,79769313486232E308 do -4,94065645841247E-324 dla liczb ujemnych oraz od 4,94065645841247E-324 do 1,79769313486232E308 dla liczb dodatnich. W języku Visual Basic znakiem deklaracji typu odpowiadającym typowi Double jest znak numeru (#).

• typ danych Decimal

Typ danych zawierający liczby dziesiętne skalowane przez potęgę liczby 10. Dla liczb skalowanych przez zero, tzn. liczb bez cyfr po przecinku dziesiętnym, zakres wynosi +/-79 228 162 514 264 337 593 543 950 335. Dla liczb z 28 miejscami po przecinku zakres wynosi +/-7,9228162514264337593543950335. Najmniejszą niezerową liczbą, która może być przedstawiona jako liczba typu Decimal jest 0,0000000000000000000000000001. Warto zwrócić uwagę, że obecnie typ danych Decimal może być używany tylko w obrębie typu Variant. Nie można zadeklarować zmiennej typu Decimal. Można natomiast za pomocą funkcji CDec utworzyć typ Variant o podtypie Decimal.

• typ danych Date

Typ danych używany do przechowywania dat i godzin w postaci liczb rzeczywistych. Zmienne typu Date są przechowywane jako liczby 64-bitowe (8-bajtowe). Wartość na lewo od przecinka dziesiętnego jest odpowiednikiem daty, a wartość na prawo od przecinka — odpowiednikiem godziny.

• typ danych String

Typ danych stanowiący sekwencję następujących po sobie znaków, które interpretowane są jako znaki tekstowe, a nie jako określone wartości numeryczne. Dane typu String mogą zawierać litery, cyfry, spacje i znaki przestankowe. Jako dane typu String można przechowywać ciągi znaków o stałej długości zawierające od 0 do około 63 K znaków oraz ciągi znaków o zmiennej długości zawierające od 0 do około 2 miliardów znaków. W języku Visual Basic znakiem deklaracji typu odpowiadającym typowi String jest znak dolara ($).

• typ danych Variant

Specjalny typ danych, które mogą oprócz danych liczbowych, ciągów znaków lub dat zawierać także wartości specjalne Empty i Null. Typ Variant rezerwuje 16 bajtów na dane numeryczne, co pozwala na przechowywanie liczb o zakresie takim jak dla typu Decimal, lub 22 bajty na ciąg znaków (łącznie z informacją o długości), co pozwala na przechowywanie dowolnego tekstu. Sposób traktowania danych typu Variant określa funkcja VarType. Wszystkie zmienne, dla których nie został jawnie zadeklarowany inny typ danych, należą do typu Variant.

• typ zdefiniowany przez użytkownika

Dowolny typ danych zdefiniowany za pomocą instrukcji Type. Typy danych zdefiniowane przez użytkownika mogą zawierać jeden lub więcej elementów dowolnego typu. Tablice typów definiowanych przez użytkownika oraz innych typów tworzone są za pomocą instrukcji Dim. Typy zdefiniowane przez użytkownika mogą zawierać tablice dowolnego typu.

• typ obiektu Obiekt

Typ obiektu udostępniony przez aplikację poprzez interfejs automatyzacji, na przykład Application, File, Range i Sheet. W celu uzyskania kompletnej listy dostępnych obiektów należy użyć Przeglądarki obiektów lub przejrzeć dokumentację aplikacji.