SQL-DB Operations

هذا الـ function block يتيح لك أداء مهام SQL الشائعة (INSERT, QUERY, UPDATE, DELETE, EXECUTE) على قاعدة بيانات متصلة. يوفر واجهة بسيطة لاختيار العملية المطلوبة، إدخال اسم الجدول عند الحاجة، وتمرير المدخلات المطلوبة عبر المقابس (sockets). تُنفذ العمليات في الخلفية حتى تبقى الواجهة سريعة الاستجابة.

📥 Inputs (sockets)

اعتمادًا على العملية المحددة، يعرض البلوك مقابس إدخال مختلفة. كل اسم مذكور أدناه هو مقبس يمكنك توصيله ببلوكات أخرى.

مقابس شائعة تستخدم في كل الطرق

• Enable يجب أن تكون محددة على true لتشغيل العملية المختارة.

• DB Client مرجع عميل قاعدة البيانات المقدم بواسطة بلوك اتصال منفصل (راجع "Tips and Tricks").

مقابس خاصة بكل طريقة

• INSERT

  • JSON Data البيانات المراد إدراجها في الجدول المختار (JSON/dictionary).

• QUERY

  • Query String سلسلة SQL SELECT أو أي استعلام آخر لتشغيله.

• UPDATE

  • JSON Data قيم التحديث (JSON/dictionary).

  • JSON Data(Where Conditions) شروط WHERE لتحديد الصفوف التي سيتم تحديثها.

• DELETE

  • JSON Data(Where Conditions) شروط WHERE لتحديد الصفوف التي سيتم حذفها.

• EXECUTE

  • Statement String جملة SQL خام للتنفيذ (استخدمها بحذر).

ملاحظة: سيُظهر البلوك أو يخفي حقل إدخال Table Name اعتمادًا على العملية المختارة.

📤 Outputs (sockets)

• Output Data يُرجع نتيجة العملية (على سبيل المثال صفوف الاستعلام، معلومات الصفوف المتأثرة، أو بيانات خاصة بالعملية).

• Success? قيمة منطقية تشير إلى ما إذا كانت العملية قد اكتملت بنجاح.

🕹️ Controls (widgets)

• Select SQL Operation قائمة منسدلة لاختيار واحدة من: INSERT / QUERY / UPDATE / DELETE / EXECUTE. تغيير الخيار يحدّث مقابس الإدخال المتاحة لتطابق العملية المختارة.

• Table Name حقل نصي لاسم الجدول المستهدف. يُخفي تلقائيًا عندما لا يكون مطلوبًا (مثلاً عند استخدام EXECUTE).

⚙️ آلية التشغيل (Running mechanism)

• يعمل البلوك فقط عندما يستقبل مقبس Enable قيمة true.

• يتطلب وجود مقبس DB Client صالحًا موصولًا (عادةً يتم توفيره بواسطة بلوك اتصال بقاعدة البيانات).

• عند التشغيل، ينفذ البلوك العملية المختارة في الخلفية ويُرجع Output Data وSuccess? عند الانتهاء.

• أي مشاكل (مثل مدخلات غير صالحة، عميل مفقود، JSON غير صالح، أو أخطاء SQL) يتم الإبلاغ عنها في منطقة الرسائل/السجل داخل البلوك.

✨ الميزات الرئيسية

• مقابس ديناميكية تتكيف مع العملية المختارة لواجهة أنظف.

• تنفيذ في الخلفية للحفاظ على استجابة الواجهة أثناء نداءات قاعدة البيانات طويلة الأمد.

• مدخلات JSON بسيطة لـ INSERT و UPDATE لتسهيل تغذية البيانات الجدولية.

• مؤشر نجاح واضح وبيانات نتيجة مرجعة للمعالجة اللاحقة.

📝 تعليمات الاستخدام

1. وفّر عميل قاعدة البيانات إلى مقبس DB Client (راجع Tips and Tricks).

2. اختر العملية المطلوبة عبر Select SQL Operation.

3. إذا لزم الأمر، أدخل اسم الجدول في Table Name.

4. وصل مقابس البيانات المطلوبة للعملية المختارة (مثلاً JSON Data للـ INSERT).

5. أرسل إشارة true إلى Enable لتشغيل العملية.

6. افحص Output Data وSuccess? لمتابعة المعالجة في السيناريو الخاص بك.

💡 Tips and Tricks

• لإنشاء الاتصالات، استخدم SQL-DB Client Connect لإنشاء وتزويد مقبس DB Client.

• حضّر بيانات الإدراج/التحديث باستخدام Data to JSON حتى تتطابق صيغة البيانات مع المدخلات المتوقعة (JSON/dictionary).

• إذا كنت تبني جمل SQL ديناميكيًا، استخدم String Input أو String Merge لتكوين الاستعلام أو الجملة قبل تمريرها إلى Query String أو Statement String.

• احفظ أو شارك عملاء DB أو النتائج الشائعة الاستخدام باستخدام Data Write Local / Data Read Local أو النسخ العالمية للوصول عبر السيناريوهات.

• استخدم Parse Data Dictionary لاستخراج الحقول من صفوف الاستعلام المرجعة وتمريرها إلى بلوكات أخرى.

• استخدم Debug Input لتسجيل وفحص البيانات الوسيطة الداخلة إلى البلوك عند استكشاف الأخطاء وإصلاحها.

• لحفظ نتائج الاستعلام لاستخدام لاحق، اجمع مع CSV Export لكتابة Output Data إلى ملف.

🛠️ استكشاف الأخطاء وإصلاحها (Troubleshooting)

• DB Client غير صالح تأكد من توصيل عميل قاعدة بيانات صحيح (استخدم SQL-DB Client Connect). سيعرض البلوك خطأ إذا كان العميل مفقودًا أو غير صالح.

• العملية تعيد خطأ راجع حمولة JSON أو سلسلة SQL المقدمة للتأكد من صحتها. استخدم Debug Input أو Parse Data Dictionary لفحص المدخلات والنتائج.

• لا يوجد استجابة أو انتظار طويل البلوك ينفذ العمليات في الخلفية، لكن الاستعلامات الطويلة قد تستغرق وقتًا. اجعل الاستعلامات أصغر أو تحقق من أن قاعدة البيانات متاحة وتستجيب.

• JSON غير صالح عند استخدام مدخلات JSON، تحقق من صحة JSON باستخدام Data to JSON أو افحص المحتوى باستخدام بلوكات التسجيل قبل التوصيل.

إذا استمرت المشاكل، فراجع مخرجات الرسائل/السجل داخل البلوك للعثور على تلميحات وضبط المدخلات أو إعدادات قاعدة البيانات وفقًا لذلك.