نام (NAME)

findscu - کلاینت ارسال کوئری و جستجوی اطلاعات در سامانه DICOM (کلاس SCU)

خلاصه دستور (SYNOPSIS)

findscu [options] peer port [dcmfile-in...]

توضیحات (DESCRIPTION)

برنامهٔ findscu یک SCU (کاربر ردهٔ سرویس) را برای ردهٔ سرویس Query/Retrieve و ردهٔ سرویس Basic Worklist Management پیاده‌سازی می‌کند. برنامهٔ findscu تنها از قابلیت جستجو (کوئری) با استفاده از پیام C-FIND پشتیبانی می‌کند. این برنامه کلیدهای جستجو را به یک SCP ارسال کرده و منتظر پاسخ‌ها می‌ماند. از این برنامه می‌توان برای آزمودن SCPهای رده‌های سرویس Query/Retrieve و Basic Worklist Management استفاده کرد.

پارامترها (PARAMETERS)

peer        نام میزبان طرف ارتباطی DICOM
port        شماره درگاه tcp/ip طرف ارتباطی
dcmfile-in  فایل(های) کوئری DICOM

گزینه‌ها (OPTIONS)

گزینه‌های عمومی (general options)

-h    --help
        چاپ این متن راهنما و خروج
      --version
        چاپ اطلاعات نسخه و خروج
      --arguments
        چاپ آرگومان‌های بسط‌یافتهٔ خط فرمان
-q    --quiet
        حالت بی‌صدا، عدم چاپ هشدارها و خطاها
-v    --verbose
        حالت پرگو، چاپ جزئیات پردازش
-d    --debug
        حالت اشکال‌زدایی، چاپ اطلاعات اشکال‌زدایی
-ll   --log-level  [l]evel: string constant
        (fatal, error, warn, info, debug, trace)
        استفاده از سطح l برای ثبت‌کننده وقایع (logger)
-lc   --log-config  [f]ilename: string
        استفاده از فایل پیکربندی f برای ثبت‌کننده وقایع

گزینه‌های شبکه (network options)

بازنویسی کلیدهای تطبیق (matching keys):
  -k    --key  [k]ey: gggg,eeee="str", path or dictionary name="str"
          بازنویسی کلید تطبیق
مدل اطلاعاتی جستجو (کوئری):
  -W    --worklist
          استفاده از مدل اطلاعاتی فهرست کاری مدالیته (پیش‌فرض)
  -P    --patient
          استفاده از مدل اطلاعاتی ریشه بیمار (patient root)
  -S    --study
          استفاده از مدل اطلاعاتی ریشه مطالعه (study root)
  -O    --psonly
          استفاده از مدل اطلاعاتی فقط بیمار/مطالعه (patient/study only)
نسخه پروتکل IP:
  -i4   --ipv4
          استفاده انحصاری از IPv4 (پیش‌فرض)
  -i6   --ipv6
          استفاده انحصاری از IPv6
  -i0   --ip-auto
          استفاده از بررسی DNS برای تعیین خودکار پروتکل IP
عناوین موجودیت برنامه (AE Titles):
  -aet  --aetitle  [a]etitle: string
          تنظیم عنوان AE فراخواننده من (پیش‌فرض: FINDSCU)
  -aec  --call  [a]etitle: string
          تنظیم عنوان AE فراخوانده‌شده طرف ارتباط (پیش‌فرض: ANY-SCP)
نمایش‌های مقدار (VR) پس از سال ۱۹۹۳:
  +u    --enable-new-vr
          فعال‌سازی پشتیبانی از VRهای جدید (UN/UT) (پیش‌فرض)
  -u    --disable-new-vr
          غیرفعال‌سازی پشتیبانی از VRهای جدید، تبدیل به OB
نحوهای انتقال (TS) پیشنهادی برای ارسال:
  -x=   --propose-uncompr
          پیشنهاد تمام TSهای فشرده‌نشده، با VR صریح و
          ترتیب بایت محلی در ابتدا (پیش‌فرض)
  -xe   --propose-little
          پیشنهاد تمام TSهای فشرده‌نشده، با VR صریح و
          little endian در ابتدا
  -xb   --propose-big
          پیشنهاد تمام TSهای فشرده‌نشده، با VR صریح و
          big endian در ابتدا
  -xd   --propose-deflated
          پیشنهاد TS فشرده‌شده با deflate با VR صریح little endian
          و تمامی نحوهای انتقال فشرده‌نشده
  -xi   --propose-implicit
          فقط پیشنهاد دادن نحو انتقال با VR ضمنی little endian
سطح فشرده‌سازی deflate (تنها همراه با --propose-deflated):
  +cl   --compression-level  [l]evel: integer (پیش‌فرض: 6)
          0=فشرده‌نشده، 1=سریع‌ترین، 9=بهترین فشرده‌سازی
سایر گزینه‌های شبکه:
  -to   --timeout  [s]econds: integer (پیش‌فرض: نامحدود)
          مهلت زمانی برای درخواست‌های اتصال
  -ts   --socket-timeout  [s]econds: integer (پیش‌فرض: 60)
          مهلت زمانی برای سوکت شبکه (0 برای نامحدود)
  -ta   --acse-timeout  [s]econds: integer (پیش‌فرض: 30)
          مهلت زمانی برای پیام‌های ACSE
  -td   --dimse-timeout  [s]econds: integer (پیش‌فرض: نامحدود)
          مهلت زمانی برای پیام‌های DIMSE
  -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
          تنظیم حداکثر pdu دریافتی به n بایت (پیش‌فرض: 16384)
        --repeat  [n]umber: integer
          تکرار به تعداد n بار
        --abort
          قطع اضطراری ارتباط (abort) به‌جای رهاسازی عادی آن (release)
        --cancel  [n]umber: integer
          لغو پس از دریافت n پاسخ (پیش‌فرض: هرگز)

گزینه‌های امنیت لایه انتقال (TLS)

پشته پروتکل انتقال:
  -tls  --disable-tls
          استفاده از اتصال عادی TCP/IP (پیش‌فرض)
  +tls  --enable-tls  [p]rivate key file, [c]ertificate file: string
          استفاده از اتصال امن و احرازهویت‌شده TLS
  +tla  --anonymous-tls
          استفاده از اتصال امن TLS بدون گواهی
گذرواژه کلید خصوصی (تنها همراه با --enable-tls):
  +ps   --std-passwd
          درخواست از کاربر برای وارد کردن گذرواژه در stdin (پیش‌فرض)
  +pw   --use-passwd  [p]assword: string
          استفاده از گذرواژه مشخص‌شده
  -pw   --null-passwd
          استفاده از رشته خالی به عنوان گذرواژه
قالب فایل کلید و گواهی:
  -pem  --pem-keys
          خواندن کلیدها و گواهی‌ها در قالب فایل PEM (پیش‌فرض)
  -der  --der-keys
          خواندن کلیدها و گواهی‌ها در قالب فایل DER
مرجع صدور گواهی (CA):
  +cf   --add-cert-file  [f]ilename: string
          افزودن فایل گواهی به فهرست گواهی‌ها
  +cd   --add-cert-dir  [d]irectory: string
          افزودن گواهی‌های موجود در پوشه d به فهرست گواهی‌ها
  +crl  --add-crl-file  [f]ilename: string
          افزودن فایل فهرست ابطال گواهی (CRL)
          (به همراه فعال‌سازی ضمنی --enable-crl-vfy)
  +crv  --enable-crl-vfy
          فعال‌سازی اعتبارسنجی CRL گواهی برگ (leaf)
  +cra  --enable-crl-all
          فعال‌سازی اعتبارسنجی CRL کل زنجیره
نمایه امنیتی:
  +ph   --list-profiles
          فهرست کردن نمایه‌های TLS پشتیبانی‌شده و خروج
  +pg   --profile-8996
          نمایه BCP 195 RFC 8996 TLS (پیش‌فرض)
  +pm   --profile-8996-mod
          نمایه اصلاح‌شده BCP 195 RFC 8996 TLS
          # تنها در صورتی در دسترس است که کتابخانه زیرین TLS از تمام
          # ویژگی‌های TLS لازم برای این نمایه پشتیبانی کند
  +py   --profile-bcp195-nd
          نمایه Non-downgrading BCP 195 TLS (منسوخ‌شده)
  +px   --profile-bcp195
          نمایه BCP 195 TLS (منسوخ‌شده)
  +pz   --profile-bcp195-ex
          نمایه Extended BCP 195 TLS (منسوخ‌شده)
  +pb   --profile-basic
          نمایه Basic TLS Secure Transport Connection (منسوخ‌شده)
          # تنها در صورتی در دسترس است که کتابخانه زیرین TLS از 3DES پشتیبانی کند
  +pa   --profile-aes
          نمایه AES TLS Secure Transport Connection (منسوخ‌شده)
  +pn   --profile-null
          ارتباط احرازهویت‌شده رمزنگاری‌نشده
          (منسوخ‌شده، در IHE ATNA استفاده می‌شد)
مجموعه رمز (ciphersuite):
  +cc   --list-ciphers
          فهرست کردن مجموعه‌های رمز TLS پشتیبانی‌شده و خروج
  +cs   --cipher  [c]iphersuite name: string
          افزودن مجموعه رمز به فهرست مجموعه‌های مورد مذاکره
نشانگر نام سرور (SNI):
        --no-sni
          عدم استفاده از SNI (پیش‌فرض)
        --request-sni  [s]erver name: string
          درخواست نام سرور s
تولیدکننده شبه‌تصادفی:
  +rs   --seed  [f]ilename: string
          مقداردهی اولیه (seed) تولیدکننده تصادفی با محتویات f
  +ws   --write-seed
          بازنویسی مقدار seed اصلاح‌شده (تنها همراه با --seed)
  +wf   --write-seed-file  [f]ilename: string (تنها همراه با --seed)
          نوشتن مقدار seed اصلاح‌شده در فایل f
احراز هویت طرف ارتباط (peer):
  -rc   --require-peer-cert
          اعتبارسنجی گواهی طرف ارتباط؛ در صورت عدم وجود ناموفق شود (پیش‌فرض)
  -ic   --ignore-peer-cert
          عدم اعتبارسنجی گواهی طرف ارتباط

گزینه‌های خروجی (output options)

عمومی:
  -od   --output-directory  [d]irectory: string (پیش‌فرض: ".")
          نوشتن فایل‌های خروجی در پوشهٔ موجود d
تصحیح خودکار داده‌ها:
  +dc   --enable-correction
          فعال‌سازی تصحیح خودکار داده‌ها
  -dc   --disable-correction
          غیرفعال‌سازی تصحیح خودکار داده‌ها (پیش‌فرض)
پاسخ‌های C-FIND:
  +sr   --show-responses
          ارسال همیشگی پاسخ‌ها به ثبت‌کننده وقایع (logger)
  -sr   --hide-responses
          عدم ارسال پاسخ‌ها به ثبت‌کننده وقایع
  -X    --extract
          استخراج پاسخ‌ها در فایل‌های DICOM (به صورت rsp0001.dcm...)
  -Xx   --extract-xml
          استخراج پاسخ‌ها در فایل‌های XML (به صورت rsp0001.xml...)
  -Xs   --extract-xml-single  [f]ilename: string
          استخراج تمام پاسخ‌ها در فایل XML داده‌شده f
  -Xlo  --limit-output  [n]umber: integer
          محدود کردن تعداد پاسخ‌های استخراج‌شده در فایل به n
          (پیش‌فرض: نامحدود)

نکات (NOTES)

هر فایلی که در خط فرمان ارائه شود، به عنوان بخشی از یک درخواست C-FIND به SCP ارسال خواهد شد. فایل جستجو (کوئری) باید یک مجموعه داده معتبر DICOM حاوی بخش dataset از پیام C-FIND-RQ باشد. برای مثال، فایل کوئری می‌تواند با استفاده از ابزار dump2dcm از روی اسکریپتی شبیه به نمونهٔ زیر ایجاد شود:

# query patient names and IDs
(0008,0052) CS [PATIENT]     # QueryRetrieveLevel
(0010,0010) PN []            # PatientName
(0010,0020) LO []            # PatientID

ویژگی‌های مجزای هر فایل ارسالی را می‌توان با استفاده از گزینهٔ -k اصلاح کرد یا تکمیل نمود. برای نمونه دستور:

findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm

هنگامی که به SCP با نام caesar در درگاه 5678 پروتکل TCP/IP ارسال شود، موجب می‌گردد که هر ویژگی PatientName در patqry.dcm دارای مقدار "HEWETT*" شود. اگر چنین ویژگی‌ای از قبل وجود داشته باشد جایگزین می‌شود و در صورت عدم وجود، درج خواهد شد. گزینهٔ -k می‌تواند بیش از یک بار تکرار شود. بخش مقدار (بعد از '=') می‌تواند حذف شود که باعث می‌شود ویژگی با طول صفر ارسال گردد.

در نسخه‌های پیشین findscu، کلیدهای تگ بدون پرانتز در اطراف شماره گروه و عنصر مشخص می‌شدند، مانند "0010,0010" به‌جای "(0010,0010)". مهاجرت به نحو جدید توصیه می‌شود؛ با این حال، نحو قدیمی همچنان کار می‌کند.

همچنین گزینهٔ -k به‌جای تگ‌های عنصر، نام‌های واژه‌نامه (dictionary names) را برای مشخص کردن عناصر DICOM می‌پذیرد. برای نمونه، فراخوانی findscu در بالا می‌تواند بدین شکل نوشته شود:

findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm

مشخص کردن توالی‌ها (sequences)، آیتم‌ها و ویژگی‌های تودرتو نیز با استفاده از گزینهٔ -k امکان‌پذیر است. در این حالت‌ها، باید از یک نشانه‌گذاری ویژه به نام نشانه‌گذاری «مسیر» (path notation) استفاده شود، مانند:

findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678

این دستور با مشخص کردن تگ (0040,0100) یعنی "Scheduled Procedure StepSequence" و ویژگی "Modality" در آیتم اول این توالی با مقدار "CT"، سرور فهرست کاری (worklist server) در میزبان caesar را برای هرگونه اقدام برنامه‌ریزی‌شده مدالیته‌های CT جستجو می‌کند. جزئیات مربوط به این نشانه‌گذاری مسیر را می‌توان در مستندات dcmodify یافت.

چنانچه هیچ فایلی در خط فرمان مشخص نشود، جستجو باید به صورت کامل با یک یا چند گزینهٔ -k تعیین گردد. در صورت ارائه چندین فایل کوئری، برنامهٔ findscu چندین درخواست C-FIND به SCP ارسال خواهد کرد.

هر مجموعه از شناسه‌های پاسخ دریافت‌شده، به ثبت‌کننده وقایع (logger) ارسال می‌شود، مگر اینکه گزینهٔ --hide-responses، هر یک از گونه‌های --extract در زیر، گزینهٔ --quiet یا یک پیکربندی مناسب برای logger استفاده شده باشد. در چنین شرایطی، خروجی به ثبت‌کننده وقایع را می‌توان با گزینهٔ --show-responses اجبار کرد.

علاوه بر این، مجموعه داده‌های پاسخ را می‌توان به صورت فایل‌های مجزای DICOM (با گزینهٔ --extract) یا فایل‌های XML (با گزینهٔ --extract-xml) استخراج کرد. قالب خروجی مورد دوم در فایل dcm2xml.dtd (که با عنصر سطح بالا "data-set" آغاز می‌شود) شرح داده شده است. برای فایل‌های XML، ویژگی Specific Character Set به صورت خودکار به کدگذاری مناسب XML نگاشت می‌شود. اگر این کار امکان‌پذیر نباشد، برای نمونه در خصوص مجموعه‌های نویسه ISO 2022، نویسه‌های غیر ASCII و نویسه‌های با کد کمتر از ۳۲ به صورت "&#nnn;" ذخیره می‌شوند که در آن "nnn" کد عددی نویسه است. لطفاً توجه داشته باشید که این امر ممکن است منجر به ارجاعات موجودیت نویسه‌ای نامعتبر (مانند "" برای ESC) شود و موجب گردد اکثر تجزیه‌کننده‌های XML سند را رد کنند.

به عنوان روشی جایگزین، تمام مجموعه داده‌های پاسخ یک ارتباط (association) را می‌توان با گزینهٔ --extract-xml-single در یک فایل XML واحد استخراج کرد. عنصر سطح بالای سند XML عبارت از "responses" (همراه با ویژگی "type" با مقدار "C-FIND") خواهد بود. مجموعه داده‌های مجزا همانند آنچه در بالا شرح داده شد ذخیره می‌شوند. در صورت فعال بودن پشتیبانی از تبدیل مجموعه نویسه، از کدگذاری UTF-8 استفاده می‌شود، یعنی تمام مجموعه داده‌ها به کدگذاری UTF-8 تبدیل می‌شوند (که برای جلوگیری از بروز مشکلات مرتبط با نویسه‌های غیر ASCII در هنگام استفاده از مجموعه‌های نویسهٔ متفاوت، اکیداً توصیه می‌شود).

انطباق با دایکام (DICOM Conformance)

برنامهٔ findscu از SOP Classهای زیر به‌عنوان یک SCU پشتیبانی می‌کند:

FINDPatientRootQueryRetrieveInformationModel       1.2.840.10008.5.1.4.1.2.1.1
FINDStudyRootQueryRetrieveInformationModel         1.2.840.10008.5.1.4.1.2.2.1
FINDPatientStudyOnlyQueryRetrieveInformationModel  1.2.840.10008.5.1.4.1.2.3.1
FINDModalityWorklistInformationModel               1.2.840.10008.5.1.4.31

برنامهٔ findscu بسته به گزینه‌های خط فرمان (-P، -S، -O یا -W)، بافت‌های ارائه‌دهنده (presentation contexts) را برای یکی از SOP Classهای پشتیبانی‌شدهٔ فوق پیشنهاد خواهد داد. به‌طور کلی، نحوهای انتقال زیر پشتیبانی می‌شوند:

LittleEndianImplicitTransferSyntax                 1.2.840.10008.1.2
LittleEndianExplicitTransferSyntax                 1.2.840.10008.1.2.1
DeflatedExplicitVRLittleEndianTransferSyntax       1.2.840.10008.1.2.1.99 (*)
BigEndianExplicitTransferSyntax                    1.2.840.10008.1.2.2

(*) در صورتی که همراه با پشتیبانی از zlib کامپایل شده باشد (خروجی --version را ببینید)

اینکه کدام نحوهای انتقال و با چه ترتیبی در واقع پیشنهاد شوند، با گزینه‌های --propose قابل تعیین است.

برنامهٔ findscu از مذاکرهٔ بسط‌یافته (extended negotiation) پشتیبانی نمی‌کند.

ثبت وقایع (LOGGING)

سطح خروجی ثبت وقایع در ابزارهای مختلف خط فرمان و کتابخانه‌های زیربنایی توسط کاربر قابل تعیین است. به‌طور پیش‌فرض، فقط خطاها و هشدارها در جریان خطای استاندارد نوشته می‌شوند. با استفاده از گزینهٔ --verbose، پیام‌های اطلاعاتی مانند جزئیات پردازش نیز گزارش می‌شوند. گزینهٔ --debug می‌تواند برای دریافت جزئیات بیشتر دربارهٔ فعالیت‌های درونی، برای مثال با اهداف اشکال‌زدایی به‌کار رود. سایر سطوح ثبت وقایع با استفاده از گزینهٔ --log-level قابل انتخاب هستند. در حالت --quiet فقط خطاهای مهلک گزارش می‌شوند. در رخدادهای خطای بسیار وخیم از این دست، برنامه معمولاً خاتمه می‌یابد. برای جزئیات بیشتر دربارهٔ سطوح مختلف ثبت وقایع، به مستندات ماژول «oflog» مراجعه کنید.

در صورتی که خروجی ثبت وقایع باید درون یک فایل (اختیاراً به همراه چرخش فایل لاگ)، در syslog (یونیکس) یا event log (ویندوز) نوشته شود، می‌توان از گزینهٔ --log-config استفاده کرد. این فایل پیکربندی همچنین امکان هدایت تنها پیام‌های خاصی به یک جریان خروجی معین، و فیلتر کردن پیام‌های خاص بر اساس ماژول یا برنامه‌ای که در آن ایجاد شده‌اند را فراهم می‌کند. یک نمونه فایل پیکربندی در <etcdir>/logger.cfg ارائه شده است.

خط فرمان (COMMAND LINE)

تمامی ابزارهای خط فرمان از نشانه‌گذاری زیر برای پارامترها استفاده می‌کنند: قلاب‌ها مقادیر اختیاری را در بر می‌گیرند (0-1)، سه نقطهٔ پایانی نشان می‌دهند که چندین مقدار مجاز است (1-n)، و ترکیبی از هر دو به معنای 0 تا n مقدار است.

گزینه‌های خط فرمان به ترتیب با یک علامت پیشوند «+» یا «-» از پارامترها متمایز می‌شوند. معمولاً ترتیب و موقعیت گزینه‌های خط فرمان اختیاری است (یعنی می‌توانند در هر جایی ظاهر شوند). با این حال، اگر گزینه‌ها مانعة‌الجمع باشند، گزینه‌ای که در راست‌ترین موقعیت قرار دارد اعمال می‌شود. این رفتار با قواعد استاندارد ارزیابی در شل‌های متداول یونیکس مطابقت دارد.

علاوه بر این، یک یا چند فایل دستور می‌توانند با استفاده از علامت «@» به عنوان پیشوند نام فایل مشخص شوند (مانند @command.txt). چنین آرگومان دستوری پیش از هرگونه ارزیابی بیشتر، با محتوای فایل متنی مربوطه جایگزین می‌شود (چندین نویسهٔ فاصلهٔ خالی به عنوان یک جداکنندهٔ واحد در نظر گرفته می‌شوند، مگر آنکه بین دو علامت نقل‌قول قرار گرفته باشند). لطفاً توجه داشته باشید که یک فایل دستور نمی‌تواند حاوی فایل دستور دیگری باشد. این رویکرد ساده اما مؤثر امکان خلاصه کردن ترکیب‌های متداول گزینه‌ها/پارامترها را فراهم کرده و از خطوط فرمان طولانی و گیج‌کننده جلوگیری می‌کند (یک نمونه در فایل <datadir>/dumppat.txt ارائه شده است).

محیط (ENVIRONMENT)

ابزار findscu تلاش خواهد کرد فرهنگ‌های دادهٔ DICOM مشخص‌شده در متغیر محیطی DCMDICTPATH را بارگذاری کند. به‌طور پیش‌فرض، یعنی در صورتی که متغیر محیطی DCMDICTPATH تنظیم نشده باشد، فایل <datadir>/dicom.dic بارگذاری خواهد شد مگر اینکه فرهنگ داده درون برنامه تعبیه شده باشد (حالت پیش‌فرض برای ویندوز).

رفتار پیش‌فرض ارجح است و متغیر محیطی DCMDICTPATH تنها زمانی باید استفاده شود که فرهنگ‌های دادهٔ جایگزین مورد نیاز باشند. ساختار متغیر محیطی DCMDICTPATH همانند متغیر PATH در پوستهٔ یونیکس است که در آن دونقطه (":") ورودی‌ها را از هم جدا می‌کند. در سیستم‌های ویندوز، از نقطه ویرگول (";") به عنوان جداکننده استفاده می‌شود. کد فرهنگ داده تلاش خواهد کرد هر فایل مشخص‌شده در متغیر محیطی DCMDICTPATH را بارگذاری کند. چنانچه هیچ فرهنگ داده‌ای بارگذاری نشود، این یک خطا در نظر گرفته می‌شود.

بسته به گزینه‌های مشخص‌شده در خط فرمان، ابزار findscu تلاش خواهد کرد تا جدول‌های نگاشت مجموعه نویسه را بارگذاری کند. این حالت زمانی رخ می‌دهد که DCMTK با کتابخانه oficonv (که حالت پیش‌فرض است) کامپایل شده باشد و جدول‌های نگاشت درون کتابخانه گنجانده نشده باشند (حالت پیش‌فرض هنگامی که DCMTK از کتابخانه‌های مشترک استفاده می‌کند).

انتظار می‌رود فایل‌های جدول نگاشت در <datadir> متعلق به DCMTK قرار داشته باشند. متغیر محیطی DCMICONVPATH می‌تواند برای مشخص کردن مکانی دیگر استفاده شود. در صورت تعیین مکانی متفاوت، آن جدول‌های نگاشت جایگزین هرگونه جدول درونی نیز خواهند شد.