Υπηρεσία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

Παράμετροι:

Παράδειγμα:

Σε 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

Παράμετροι:

Παράδειγμα:

Σε 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