Υπηρεσία SFDatabases.Dataset

Περιεχόμενα

# ΥπηρεσίαSFDatabases.Dataset

Η υπηρεσία Dataset χρησιμοποιείται για την αναπαράσταση δεδομένων σε πίνακα που παράγονται από μια βάση δεδομένων. Με αυτήν την υπηρεσία είναι δυνατά τα:

- Πλοήγηση και πρόσβαση στα δεδομένα σε ένα σύνολο δεδομένων.

- Ενημέρωση, εισαγωγή και κατάργηση εγγραφών σε ένα σύνολο δεδομένων.

Η ενημέρωση και η εισαγωγή εγγραφών με χρήση της υπηρεσίας Dataset είναι πιο αργή από τη χρήση εντολών SQL. Κατά την ενημέρωση ή την εισαγωγή μεγάλων ποσοτήτων εγγραφών, συνιστάται η χρήση προτάσεων SQL αντί των μεθόδων αυτής της υπηρεσίας.

## Επίκληση υπηρεσίας

Πριν χρησιμοποιήσετε την υπηρεσία Dataset, πρέπει να φορτωθεί ή να εισαχθεί η βιβλιοθήκη ScriptForge:

• Οι μακροεντολές Basic απαιτούν τη φόρτωση της βιβλιοθήκης ScriptForge χρησιμοποιώντας την ακόλουθη πρόταση:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Τα σενάρια Python απαιτούν εισαγωγή από την ενότητα scriptforge:
από το scriptforge import CreateScriptService

Η υπηρεσία Dataset καλείται χρησιμοποιώντας τη μέθοδο CreateDataset, η οποία μπορεί να κληθεί είτε από μια παρουσία υπηρεσίας Database, είτε από άλλη παρουσία Dataset.

##### Σε Basic

Το ακόλουθο παράδειγμα δημιουργεί ένα Dataset από τον πίνακα "Customers" που είναι αποθηκευμένος σε ένα αρχείο βάσης δεδομένων.

        oDatabase = CreateScriptService("Database", "C:\MyDatabase.odb")
        oDataset = oDatabase.CreateDataset("Customers")
        With oDataset
            Do While .MoveNext()
                oValues = .Values()
                ' ...
            Loop
            .CloseDataset()
        End With

Κατά τη δημιουργία του Dataset, η τρέχουσα εγγραφή τοποθετείται πριν από την πρώτη εγγραφή.

Το παρακάτω παράδειγμα δημιουργεί μια παρουσία Dataset φιλτράροντας το αρχικό σύνολο δεδομένων.

        oNewDataset = oDataset.CreateDataset(Filter := "[City]='New York'")

##### Σε Python

        database = CreateScriptService("Database", r"C:\MyDatabase.odb")
        dataset = database.CreateDataset("Customers")
        while dataset.MoveNext():
            values = dataset.Values
            # ...
        dataset.CloseDataset()

        new_dataset = dataset.CreateDataset(filter = "[City]='New York'")

## Ιδιότητες

Όνομα | Μόνο για ανάγνωση | Τύπος | Περιγραφή
--- | --- | --- | ---
BOF | Όχι | Boolean | Επιστρέφει True εάν η τρέχουσα θέση εγγραφής βρίσκεται πριν από την πρώτη εγγραφή στο σύνολο δεδομένων, διαφορετικά επιστρέφει False. Ορίστε αυτήν την ιδιότητα σε True για να μετακινήσετε τον δρομέα στην αρχή του συνόλου δεδομένων. Η ρύθμιση αυτής της ιδιότητας σε False αγνοείται.
DefaultValues | Ναι | Υπηρεσία Dictionary | Επιστρέφει ένα Dictionary με τις προεπιλεγμένες τιμές που χρησιμοποιούνται για κάθε πεδίο στο σύνολο δεδομένων. Τα πεδία ή οι στήλες στο σύνολο δεδομένων είναι τα κλειδιά του λεξικού. Οι τύποι πεδίων βάσης δεδομένων μετατρέπονται στους αντίστοιχους τύπους δεδομένων Basic/Python. Όταν ο τύπος πεδίου δεν έχει καθοριστεί, η προεπιλεγμένη τιμή είναι Null εάν το πεδίο είναι μηδενικό ή Empty.
EOF | Όχι | Boolean | Επιστρέφει True, εάν η τρέχουσα θέση εγγραφής βρίσκεται μετά την τελευταία εγγραφή στο σύνολο δεδομένων, διαφορετικά επιστρέφει False. Ορίστε αυτήν την ιδιότητα σε True για να μετακινήσετε τον δρομέα στο τέλος του συνόλου δεδομένων. Η ρύθμιση αυτής της ιδιότητας σε False αγνοείται.
Fields | Ναι | Array | Επιστρέφει ένα Array που περιέχει τα ονόματα όλων των πεδίων στο σύνολο δεδομένων.
Filter | Ναι | String | Επιστρέφει το φίλτρο που εφαρμόστηκε επιπλέον των ενδεχόμενων όρων WHERE στην αρχική πρόταση SQL. Αυτή η ιδιότητα εκφράζεται ως όρος WHERE χωρίς τη λέξη-κλειδί "WHERE".
OrderBy | Ναι | String | Επιστρέφει την πρόταση παραγγελίας που αντικαθιστά την ενδεχόμενη πρόταση ORDER BY που υπάρχει στην αρχική πρόταση SQL. Αυτή η ιδιότητα εκφράζεται ως πρόταση ORDER BY χωρίς τις λέξεις-κλειδιά "ORDER BY".
ParentDatabase | Ναι | Υπηρεσία Database | Επιστρέφει την παρουσία Database που αντιστοιχεί στη γονική βάση δεδομένων του τρέχοντος συνόλου δεδομένων.
RowCount | Ναι | Long | Επιστρέφει τον ακριβή αριθμό των εγγραφών στο σύνολο δεδομένων. Λάβετε υπόψη ότι η αξιολόγηση αυτής της ιδιότητας συνεπάγεται περιήγηση σε ολόκληρο το σύνολο δεδομένων, η οποία μπορεί να είναι δαπανηρή ανάλογα με το μέγεθος του συνόλου δεδομένων.
RowNumber | Ναι | Long | Επιστρέφει τον αριθμό της τρέχουσας εγγραφής που ξεκινά από το 1. Επιστρέφει 0 εάν αυτή η ιδιότητα είναι άγνωστη.
Source | Ναι | String | Επιστρέφει την πηγή του συνόλου δεδομένων. Μπορεί να είναι είτε όνομα πίνακα, όνομα ερωτήματος, ή πρόταση SQL.
SourceType | Ναι | String | Επιστρέφει την πηγή του συνόλου δεδομένων. Μπορεί να είναι μία από τις ακόλουθες τιμές συμβολοσειράς: TABLE, QUERY ή SQL.
UpdatableFields | Ναι | Array | Επιστρέφει ένα Array που περιέχει τα ονόματα των πεδίων του συνόλου δεδομένων που μπορούν να ενημερωθούν.
Values | Ναι | Array | Επιστρέφει ένα Dictionary που περιέχει τα ζεύγη (όνομα πεδίου: τιμή) της τρέχουσας εγγραφής στο σύνολο δεδομένων.
XRowSet | Ναι | Αντικείμενο UNO | Επιστρέφει το αντικείμενο com.sun.star.sdb.RowSet UNO που αντιπροσωπεύει το σύνολο των δεδομένων.

Κατάλογος μεθόδων στην υπηρεσία Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Κλείνει το τρέχον σύνολο δεδομένων. Αυτή η μέθοδος επιστρέφει True όταν είναι επιτυχής.

Συνιστάται να κλείσετε το σύνολο δεδομένων μετά τη χρήση του για να ελευθερωθούν πόροι.

### Σύνταξη:

svc.CloseDataset(): bool

### Παράδειγμα:

##### Σε Basic

          oDataset = oDatabase.CreateDataset("MyTable")
          ' ...
          oDataset.CloseDataset()

##### Σε Python

          dataset = database.CreateDataset("MyTable")
          # ...
          dataset.CloseDataset()

## CreateDataset

Επιστρέφει μια παρουσία υπηρεσίας Dataset από ένα υπάρχον σύνολο δεδομένων εφαρμόζοντας το καθορισμένο φίλτρο και τις προτάσεις ORDER BY.

### Σύνταξη:

svc.CreateDataset(opt filter: str, opt orderby: str): svc

### Παράμετροι:

filter: Καθορίζει την συνθήκη που πρέπει να ταιριάζουν οι εγγραφές για να συμπεριληφθούν στο επιστρεφόμενο σύνολο δεδομένων. Αυτό το όρισμα εκφράζεται ως πρόταση SQL WHERE χωρίς τη λέξη-κλειδί "WHERE". Εάν αυτό το όρισμα δεν έχει καθοριστεί, τότε εφαρμόζεται το φίλτρο που χρησιμοποιείται στο τρέχον σύνολο δεδομένων, διαφορετικά το τρέχον φίλτρο αντικαθίσταται από αυτό το όρισμα.

orderby: Καθορίζει τη σειρά του συνόλου δεδομένων ως πρόταση SQL ORDER BY χωρίς τη λέξη-κλειδί "ORDER BY". Εάν αυτό το όρισμα δεν προσδιορίζεται, τότε εφαρμόζεται η σειρά ταξινόμησης που χρησιμοποιείται στο τρέχον σύνολο δεδομένων, διαφορετικά η τρέχουσα σειρά ταξινόμησης αντικαθίσταται από αυτό το όρισμα.

### Παράδειγμα:

##### Σε Basic

          ' Χρησιμοποιήστε μια κενή συμβολοσειρά για να αφαιρέσετε το τρέχον φίλτρο
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Παραδείγματα κοινών φίλτρων
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
          Είναι δυνατή η προσθήκη πρόσθετων συνθηκών στο τρέχον φίλτρο
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")

##### Σε Python

          new_dataset = dataset.CreateDataset(filter = "")
          new_dataset = dataset.CreateDataset(filter = "[Name] = 'John'")
          new_dataset = dataset.CreateDataset(filter = "[Name] LIKE 'A'")
          new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Name] LIKE 'A'")

## Delete

Διαγράφει την τρέχουσα εγγραφή από το σύνολο δεδομένων. Αυτή η μέθοδος επιστρέφει True όταν είναι επιτυχής.

Μετά από αυτήν τη λειτουργία, ο δρομέας τοποθετείται στην εγγραφή αμέσως μετά τη διαγραμμένη εγγραφή. Εάν η διαγραμμένη εγγραφή είναι η τελευταία στο σύνολο δεδομένων, τότε ο δρομέας τοποθετείται μετά από αυτήν και η ιδιότητα EOF επιστρέφει True.

### Σύνταξη:

svc.Delete(): bool

### Παράδειγμα:

##### Σε Basic

          oDataset.Delete()

##### Σε Python

          dataset.Delete()

## ExportValueToFile

Εξάγει την τιμή ενός δυαδικού πεδίου της τρέχουσας εγγραφής στο καθορισμένο αρχείο.

Εάν το καθορισμένο πεδίο δεν είναι δυαδικό, ή εάν δεν περιέχει δεδομένα, τότε το αρχείο εξόδου δεν δημιουργείται.

### Σύνταξη:

svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool

### Παράμετροι:

fieldname: Το όνομα του δυαδικού πεδίου που θα εξαχθεί, ως συμβολοσειρά με διάκριση πεζών-κεφαλαίων.

filename: Η πλήρης διαδρομή προς το αρχείο που θα δημιουργηθεί χρησιμοποιώντας τη σημειογραφία που ορίζεται στην ιδιότητα FileSystem.FileNaming.

overwrite: Ορίστε αυτό το όρισμα σε True για να επιτρέψετε την αντικατάσταση του αρχείου προορισμού (Προεπιλογή = False).

### Παράδειγμα:

Στο παρακάτω παράδειγμα, το σύνολο δεδομένων περιέχει ένα πεδίο με το όνομα "Picture" που θα εξαχθεί σε αρχείο εικόνας.

##### Σε Basic

          oDataset.ExportValueToFile("Picture", "C:\my_image.png", True)

##### Σε Python

          dataset.ExportValueToFile("Picture", r"C:\my_image.png", True)

## GetRows

Επιστρέφει τα περιεχόμενα του συνόλου δεδομένων σε έναν δισδιάστατο πίνακα, ξεκινώντας από την πρώτη εγγραφή μετά την τρέχουσα εγγραφή.

Μετά την εκτέλεση, ο δρομέας τοποθετείται στη σειρά που διαβάστηκε τελευταία ή μετά την τελευταία εγγραφή στο σύνολο δεδομένων, οπότε η ιδιότητα EOF επιστρέφει True.

Αυτή η μέθοδος μπορεί να χρησιμοποιηθεί για την ανάγνωση δεδομένων από το σύνολο δεδομένων σε κομμάτια, το μέγεθος των οποίων ορίζεται από το όρισμα maxrows.

Ο πίνακας που επιστρέφεται θα έχει πάντα δύο διαστάσεις, ακόμα κι αν το σύνολο δεδομένων περιέχει μία στήλη και μία εγγραφή.

### Σύνταξη:

svc.GetRows(header: bool, maxrows: int): any

### Παράμετροι:

header: Ορίστε αυτό το όρισμα σε True για να κάνετε την πρώτη καταχώρηση στο Array να περιέχει τις κεφαλίδες στηλών (Προεπιλογή = False).

maxrows: Καθορίζει τον μέγιστο αριθμό εγγραφών που θα επιστραφούν. Εάν ο αριθμός των υπαρχουσών εγγραφών είναι μικρότερος από maxrows, τότε το μέγεθος του πίνακα που επιστρέφεται θα είναι ίσο με τον αριθμό των εναπομεινάντων εγγραφών στο σύνολο δεδομένων. Αφήστε αυτό το όρισμα κενό ή ορίστε το στο μηδέν για να επιστρέψετε όλες τις σειρές στο σύνολο δεδομένων (Προεπιλογή = 0)

### Παράδειγμα:

Το ακόλουθο παράδειγμα διαβάζει ένα σύνολο δεδομένων σε κομμάτια των 100 σειρών μέχρι να διαβαστεί όλο το σύνολο δεδομένων.

##### Σε Basic

          Dim arrChunk As Variant, lMaxRows As Long
          lMaxRows = 100
          Do
              arrChunk = oDataset.GetRows(MaxRows := lMaxRows)
              If UBound(arrChunk, 1) >= 0 Then
                  ' ...
              End If
          Loop Until UBound(arrChunk, 1) < lMaxRows - 1

##### Σε Python

          max_rows = 100
          chunk = dataset.GetRows(maxrows = max_rows)
          while len(chunk) > 0:
              # ...
              chunk = dataset.GetRows(maxrows = max_rows)

## GetValue

Επιστρέφει την τιμή του καθορισμένου πεδίου από την τρέχουσα εγγραφή του συνόλου δεδομένων.

Εάν το καθορισμένο πεδίο είναι δυαδικό, τότε επιστρέφεται το μήκος του.

### Σύνταξη:

svc.GetValue(fieldname: str): any

### Παράμετροι:

fieldname: Το όνομα του πεδίου που θα επιστραφεί, ως συμβολοσειρά με διάκριση πεζών-κεφαλαίων.

### Παράδειγμα:

##### Σε Basic

          currId = oDataset.GetValue(FieldName := "ID")

##### Σε Python

          curr_id = dataset.GetValue(fieldname = "ID")

## Insert

Εισάγει μια νέα εγγραφή στο τέλος του συνόλου δεδομένων και αρχικοποιεί τα πεδία του με τις καθορισμένες τιμές.

Εάν το πρωτεύον κλειδί του συνόλου δεδομένων είναι μια αυτόματη τιμή, τότε αυτή η μέθοδος επιστρέφει την τιμή του πρωτεύοντος κλειδιού της νέας εγγραφής. Διαφορετικά, η μέθοδος θα επιστρέψει 0 (όταν είναι επιτυχής), ή -1 (όταν δεν είναι επιτυχής).

Τα ενημερώσιμα πεδία με ακαθόριστες τιμές αρχικοποιούνται με τις προεπιλεγμένες τιμές τους.

Εάν το καθορισμένο πεδίο είναι δυαδικό, τότε το μήκος του επιστρέφεται.

### Σύνταξη:

svc.Insert(pvargs: any): int

### Παράμετροι:

pvargs: Ένα Dictionary που περιέχει ζεύγη ονομάτων πεδίων και τις αντίστοιχες τιμές τους. Εναλλακτικά, ένας ζυγός αριθμός ορισμάτων μπορεί να καθοριστεί με εναλλασσόμενα ονόματα πεδίων (ως String) και τις τιμές τους.

### Παράδειγμα:

##### Σε Basic

Θεωρήστε έναν πίνακα με το όνομα "Customers" με 4 πεδία: "ID" (BigInt, αυτόματη τιμή και κύριο κλειδί), "Name" (VarChar), "Age" (Integer), "City" (VarChar).

Το παρακάτω παράδειγμα εισάγει μια νέα εγγραφή σε αυτό το σύνολο δεδομένων χρησιμοποιώντας ένα Dictionary.

          oDataset = oDatabase.CreateDataset("Customers")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Name", "John")
          oNewData.Add("Age", 50)
          oNewData.Add("City", "Chicago")
          lNewID = oDataset.Insert(oNewData)

Το ίδιο αποτέλεσμα μπορεί να επιτευχθεί μεταβιβάζοντας όλα τα ζεύγη πεδίων και τιμών ως ορίσματα:

          oDataset.Insert("Name", "John", "Age", 50, "City", "Chicago")

##### Σε Python

          dataset = database.CreateDataset("Customers")
          new_data = {"Name": "John", "Age": 30, "City": "Chicago"}
          new_id = dataset.Insert(new_data)

Οι ακόλουθες κλήσεις γίνονται δεκτές στην Python:

          dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
          dataset.Insert(Name = "John", Age = 50, City = "Chicago")

## MoveFirst / MoveLast

Μετακινεί τον δρομέα δεδομένων στην πρώτη (με MoveFirst) ή στην τελευταία (με MoveLast) εγγραφή.

Αυτή η μέθοδος επιστρέφει True όταν είναι επιτυχής.

Οι διαγραμμένες εγγραφές αγνοούνται με αυτήν τη μέθοδο.

### Σύνταξη:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Παράδειγμα:

##### Σε Basic

          oDataset.MoveFirst()

##### Σε Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Μετακινεί τον δρομέα δεδομένων προς τα εμπρός (με MoveNext) ή προς τα πίσω (με MovePrevious) κατά έναν δεδομένο αριθμό εγγραφών.

Αυτή η μέθοδος επιστρέφει True όταν είναι επιτυχής.

Οι διαγραμμένες εγγραφές αγνοούνται με αυτήν τη μέθοδο.

### Σύνταξη:

svc.MoveNext(offset: int = 1): bool

svc.MovePrevious(offset: int = 1): bool

### Παράμετροι:

offset: Ο αριθμός των εγγραφών με τις οποίες ο δρομέας θα μετακινηθεί προς τα εμπρός ή προς τα πίσω. Αυτό το όρισμα μπορεί να είναι αρνητική τιμή (Προεπιλογή = 1).

### Παράδειγμα:

##### Σε Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### Σε Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Φορτώνει ξανά το σύνολο δεδομένων από τη βάση δεδομένων. Οι ιδιότητες Filter και OrderBy μπορούν να οριστούν κατά την κλήση αυτής της μεθόδου.

Αυτή η μέθοδος επιστρέφει True όταν είναι επιτυχής.

Η επαναφόρτωση του συνόλου δεδομένων είναι χρήσιμη όταν οι εγγραφές έχουν εισαχθεί ή διαγραφεί από τη βάση δεδομένων. Λάβετε υπόψη ότι οι μέθοδοι CreateDataset και Reload εκτελούν παρόμοιες λειτουργίες, ωστόσο η Reload επαναχρησιμοποιεί την ίδια παρουσία κλάσης Dataset.

### Σύνταξη:

svc.Reload(opt filter: str, opt orderby: str): bool

### Παράμετροι:

filter: Καθορίζει την συνθήκη που πρέπει να ταιριάζουν οι εγγραφές για να συμπεριληφθούν στο επιστρεφόμενο σύνολο δεδομένων. Αυτό το όρισμα εκφράζεται ως πρόταση SQL WHERE χωρίς τη λέξη-κλειδί "WHERE". Εάν αυτό το όρισμα δεν έχει καθοριστεί, τότε εφαρμόζεται το φίλτρο που χρησιμοποιείται στο τρέχον σύνολο δεδομένων, διαφορετικά το τρέχον φίλτρο αντικαθίσταται από αυτό το όρισμα.

orderby: Καθορίζει τη σειρά του συνόλου δεδομένων ως πρόταση SQL ORDER BY χωρίς τη λέξη-κλειδί "ORDER BY". Εάν αυτό το όρισμα δεν προσδιορίζεται, τότε εφαρμόζεται η σειρά ταξινόμησης που χρησιμοποιείται στο τρέχον σύνολο δεδομένων, διαφορετικά η τρέχουσα σειρά ταξινόμησης αντικαθίσταται από αυτό το όρισμα.

### Παράδειγμα:

##### Σε Basic

          oDataset.Reload()
          oDataset.Reload(Filter := "[Name] = 'John'", OrderBy := "Age")

##### Σε Python

          dataset.Reload()
          dataset.Reload(Filter = "[Name] = 'John'", OrderBy = "Age")

## Update

Ενημέρωση των τιμών των καθορισμένων πεδίων στην τρέχουσα εγγραφή.

Αυτή η μέθοδος επιστρέφει True όταν είναι επιτυχής.

### Σύνταξη:

svc.Update(pvargs: any): bool

### Παράμετροι:

pvargs: Ένα Dictionary που περιέχει ζεύγη ονομάτων πεδίων και τις αντίστοιχες τιμές τους. Εναλλακτικά, ένας ζυγός αριθμός ορισμάτων μπορεί να καθοριστεί με εναλλασσόμενα ονόματα πεδίων (ως String) και τις τιμές τους.

### Παράδειγμα:

##### Σε Basic

Το παρακάτω παράδειγμα ενημερώνει την τρέχουσα εγγραφή χρησιμοποιώντας ένα Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Age", 51)
          oNewValues.Add("City", "New York")
          oDataset.Update(oNewValues)

Το ίδιο αποτέλεσμα μπορεί να επιτευχθεί μεταβιβάζοντας όλα τα ζεύγη πεδίων και τιμών ως ορίσματα:

          oDataset.Update("Age", 51, "City", "New York")

##### Σε Python

          new_values = {"Age": 51, "City": "New York"}
          dataset.Update(new_values)

          dataset.Update("Age", 51, "City", "New York")
          dataset.Update(Age = 51, City = "New York")

Όλες οι ρουτίνες ή αναγνωριστικά του ScriptForge στη Basic που έχουν το πρόθεμα χαρακτήρα υπογράμμισης "_" δεσμεύονται για εσωτερική χρήση. Δεν προορίζονται να χρησιμοποιηθούν σε μακροεντολές Basic ή σενάρια Python.

Σχετικά θέματα

SFDatabases.Database