Access

  MS Access 2010+  |  Aplication Programming Interface API  |   VBA 7.0



• Declare - instrukcja

Instrukcja wykorzystywana na poziomie modułu do deklarowania odwołań do procedur zewnętrznych zawartych w bibliotekach dołączanych dynamicznie (w pliku DLL).

• Składnia instrukcji Declare

Aby użyć funkcji API w aplikacji Accessa, 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:

  Element    Opis
PublicElement nieobowiązkowy. Używany do deklarowania procedur dostępnych we wszystkich procedurach wszystkich modułów.
PrivateElement nieobowiązkowy. Używany do deklarowania procedur dostępnych tylko wewnątrz modułu, w którym występuje deklaracja.
PtrSafe Kwalifikator ten jest obowiązkowy w VBA7 w systemach 64 bitowych. Określa, że deklaracja jest zgodna z 64 bitowymi środowiskami programistycznymi.
Sub Element nieobowiązkowy (jeden z elementów: Sub lub Function, musi wystąpić). Wskazuje, że procedura nie zwraca żadnej wartości.
Function Element nieobowiązkowy (jeden z elementów: Sub lub Function, musi wystąpić). Wskazuje, że procedura zwraca wartość, która może być wykorzystana w wyrażeniu.
nazwa Element obowiązkowy. Dowolna poprawna nazwa procedury. Należy pamiętać, że pozycje w bibliotece DLL uwzględniają wielkość liter.
Lib Element obowiązkowy. Wskazuje, że deklarowana procedura zawarta jest w pliku z kodem programu lub w bibliotece DLL. Klauzula Lib jest wymagana dla wszystkich deklaracji.
nazwa_biblioteki Element obowiązkowy. Nazwa biblioteki DLL lub pliku z kodem programu, który zawiera deklarowaną procedurę.
Alias Element nieobowiązkowy. Wskazuje, że wołana procedura ma w bibliotece DLL inną nazwę. Jest to szczególnie przydatne wtedy, gdy nazwa procedury zewnętrznej jest taka sama jak słowo kluczowe. Element Alias można wykorzystywać również wtedy, gdy procedura z biblioteki DLL ma taką samą nazwę jak zmienna publiczna, stała lub dowolna inna procedura w tym samym zakresie.
Alias jest również przydatny wtedy, gdy w nazwie procedury w bibliotece DLL występują jakiekolwiek znaki, które nie są zgodne z konwencją nazewnictwa przyjętą dla bibliotek DLL.
alias Element nieobowiązkowy. Nazwa procedury w bibliotece DLL lub w pliku z kodem programu. Jeżeli pierwszy znak nie jest znakiem numeru (#), alias jest nazwą punktu wejścia do procedury w bibliotece DLL. Jeżeli pierwszym znakiem jest znak (#), wszystkie następujące po nim znaki muszą wskazywać numer porządkowy punktu wejścia do procedury.
lista_argumentów Element nieobowiązkowy. Lista zmiennych reprezentujących argumenty przekazywane do procedury podczas jej wywołania.
typ Element nieobowiązkowy. Typ wartości zwracanej przez procedurę typu Function, mogący przyjąć następujące postaci: Byte, Boolean, Integer, Long, LongPtr, LongLong, Currency, Single, Double, Decimal (obecnie nie obsługiwany),Date, String (tylko o zmiennej długości), Variant, inny typ zdefiniowany przez użytkownika lub typ obiektu.

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]

  Element    Opis
Optional Element nieobowiązkowy. Wskazuje, że argument nie jest wymagany. Jeżeli element ten zostanie użyty, wszystkie następne argumenty na liście lista_argumentów muszą być również nieobowiązkowe i zadeklarowane z wykorzystaniem słowa kluczowego Optional. Element Optional nie może zostać użyty w stosunku do żadnego argumentu, jeżeli podano element ParamArray.
ByVal Element nieobowiązkowy. Wskazuje, że argument przekazywany jest przez wartość.
ByRef Wskazuje, że argument przekazywany jest przez odwołanie. W języku Visual Basic ByRef jest ustawieniem domyślnym.
ParamArray Element nieobowiązkowy. Wykorzystywany jest tylko jako ostatni argument na liście lista_argumentów wskazując, że ostatnim argumentem jest tablica typu Optional zawierająca elementy typu Variant. Słowo kluczowe ParamArray pozwala na podanie dowolnej liczby argumentów. Element ParamArray nie może być używany razem z elementami ByVal, ByRef lub Optional.
nazwa_zmiennej Element obowiązkowy. Nazwa zmiennej reprezentującej przekazywany do procedury argument. Musi być zgodna ze standardowymi konwencjami nazewnictwa zmiennych.
( ) Element obowiązkowy dla zmiennych tablicowych. Oznacza, że nazwa_zmiennej jest tablicą.
typ Element nieobowiązkowy. Typ argumentu przekazywanego do funkcji lub procedury, mogący przyjmować następujące postaci: Byte, Boolean, Integer, Long, LongPtr, LongLong, Currency, Single, Double, Decimal (obecnie nie obsługiwany), Date, String (tylko o zmiennej długości), Object, Variant, typ zdefiniowany przez użytkownika lub typ obiektowy.

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, PropertySub. 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, ObjectVariant (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 EmptyNull. 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, RangeSheet. W celu uzyskania kompletnej listy dostępnych obiektów należy użyć Przeglądarki obiektów lub przejrzeć dokumentację aplikacji.