1/*!
2
3\if MANPAGES
4\page wlmscpfs DICOM Basic Worklist Management SCP (based on data files)
5\else
6\page wlmscpfs wlmscpfs: DICOM Basic Worklist Management SCP (based on data files)
7\endif
8
9\section wlmscpfs_synopsis SYNOPSIS
10
11\verbatim
12wlmscpfs [options] port
13\endverbatim
14
15\section wlmscpfs_description DESCRIPTION
16
17The \b wlmscpfs application implements a Service Class Provider (SCP) for the
18Basic Worklist Management Service.  The application will listen on a specified
19TCP/IP port for incoming association requests from a Worklist Management SCU.
20In case an association was acknowledged and a worklist query was received, the
21\b wlmscpfs application will query particular files in a certain directory
22(which can be specified through corresponding program options) on the file
23system for corresponding worklist information, and it will send this
24information back to the calling Worklist Management SCU.  Aside from dealing
25with Worklist Management queries, the \b wlmscpfs application also supports
26the Verification Service Class as an SCP.
27
28\section wlmscpfs_parameters PARAMETERS
29
30\verbatim
31port  tcp/ip port number to listen on
32\endverbatim
33
34\section wlmscpfs_options OPTIONS
35
36\subsection wlmscpfs_general_options general options
37\verbatim
38  -h    --help
39          print this help text and exit
40
41        --version
42          print version information and exit
43
44        --arguments
45          print expanded command line arguments
46
47  -q    --quiet
48          quiet mode, print no warnings and errors
49
50  -v    --verbose
51          verbose mode, print processing details
52
53  -d    --debug
54          debug mode, print debug information
55
56  -ll   --log-level  [l]evel: string constant
57          (fatal, error, warn, info, debug, trace)
58          use level l for the logger
59
60  -lc   --log-config  [f]ilename: string
61          use config file f for the logger
62\endverbatim
63
64\subsection wlmscpfs_multiprocess_options multi-process options
65\verbatim
66  -s    --single-process
67          single process mode
68
69        --fork
70          fork child process for each association (default)
71\endverbatim
72
73\subsection wlmscpfs_input_options input options
74\verbatim
75general:
76
77  -dfp  --data-files-path  [p]ath: string (default: .)
78          path to worklist data files
79
80handling of worklist files:
81
82  -efr  --enable-file-reject
83          enable rejection of incomplete worklist files (default)
84
85  -dfr  --disable-file-reject
86          disable rejection of incomplete worklist files
87\endverbatim
88
89\subsection wlmscpfs_processing_options processing options
90\verbatim
91returned character set:
92
93  -cs0  --return-no-char-set
94          return no specific character set (default)
95
96  -cs1  --return-iso-ir-100
97          return specific character set ISO IR 100
98
99  -csk  --keep-char-set
100          return character set provided in file
101
102other processing options:
103
104  -nse  --no-sq-expansion
105          disable expansion of empty sequences in C-FIND
106          request messages
107\endverbatim
108
109\subsection wlmscpfs_network_options network options
110\verbatim
111preferred network transfer syntaxes:
112
113  +x=   --prefer-uncompr
114          prefer explicit VR local byte order (default)
115
116  +xe   --prefer-little
117          prefer explicit VR little endian TS
118
119  +xb   --prefer-big
120          prefer explicit VR big endian TS
121
122  +xd   --prefer-deflated
123          prefer deflated explicit VR little endian TS
124
125  +xi   --implicit
126          accept implicit VR little endian TS only
127
128network host access control (tcp wrapper):
129
130  -ac   --access-full
131          accept connections from any host (default)
132
133  +ac   --access-control
134          enforce host access control rules
135
136post-1993 value representations:
137
138  +u    --enable-new-vr
139          enable support for new VRs (UN/UT) (default)
140
141  -u    --disable-new-vr
142          disable support for new VRs, convert to OB
143
144deflate compression level (only with --prefer-deflated):
145
146  +cl   --compression-level  [l]evel: integer (default: 6)
147          0=uncompressed, 1=fastest, 9=best compression
148
149other network options:
150
151  -ta   --acse-timeout  [s]econds: integer (default: 30)
152          timeout for ACSE messages
153
154  -td   --dimse-timeout  [s]econds: integer (default: unlimited)
155          timeout for DIMSE messages
156
157        --max-associations  [a]ssocs: integer (default: 50)
158          limit maximum number of parallel associations
159
160        --refuse
161          refuse association
162
163        --reject
164          reject association if no implementation class UID
165
166        --no-fail
167          don't fail on an invalid query
168
169        --sleep-before  [s]econds: integer
170          sleep s seconds before find (default: 0)
171
172        --sleep-after  [s]econds: integer
173          sleep s seconds after find (default: 0)
174
175        --sleep-during  [s]econds: integer
176          sleep s seconds during find (default: 0)
177
178  -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
179          set max receive pdu to n bytes (default: 16384)
180
181  -dhl  --disable-host-lookup
182          disable hostname lookup
183\endverbatim
184
185\subsection wlmscp_output_options output options
186\verbatim
187general:
188
189  -rfp  --request-file-path  [p]ath: string
190          path to store request files to
191
192  -rff  --request-file-format  [f]ormat: string (default: #t.dump)
193          request file name format
194\endverbatim
195
196\section wlmscpfs_notes NOTES
197
198The semantic impacts of the above mentioned options is clear for the majority
199of options.  Some particular options, however, are so specific that they need
200detailed descriptions which will be given in this passage.
201
202The returned character set options are intended for situations in which the
203\b wlmscpfs application will return attribute values which are not composed of
204characters from the DICOM default character repertoire.  In such cases, for
205example option \e --return-iso-ir-100 can be used to specify that a response
206to a modality's worklist management C-FIND request shall contain DICOM's
207Specific Character Set attribute (0008,0005) with a corresponding value,
208indicating the character repertoire from which the characters of returned
209attribute values were taken (in this example the repertoire ISO IR 100).
210Please note that the \b wlmscpfs application will not make sure that all
211returned values are actually made up of this character repertoire; the
212application expects this to be the case.
213
214In general, the Specific Character Set attribute (0008,0005) will only be
215included in the C-FIND response if it contains any attributes that are affected
216by the character set, i.e. for value representations PN, LO, LT, SH, ST and UT.
217
218Please note that a C-FIND request which is handled by this application may
219contain DICOM's Specific Character Set attribute (0008,0005), but this
220application will never use this attribute's value for matching.  Besides, the
221question if DICOM's Specific Character Set attribute (0008,0005) will be
222contained in a C-FIND response which is returned by this application is always
223determined by the returned character set option which was specified when this
224application was started.
225
226The options --enable-file-reject and --disable-file-reject can be used to
227enable or disable a file rejection mechanism which makes sure only complete
228worklist files will be used during the matching process.  A worklist file is
229considered to be complete if it contains all necessary type 1 information
230which the SCP might have to return to an SCU in a C-FIND response message.
231Table K.6-1 in part 4 annex K of the DICOM standard lists all corresponding
232type 1 attributes (see column "Return Key Type").
233
234\subsection wlmscpfs_request_files Writing Request Files
235
236Providing option \e --request-file-path enables writing of the incoming C-FIND
237requests into text files.  The option value provides the target directory where
238these files will be stored.  All request files are stored in "dump" format as
239provided by the \b dcmdump tool and are raw, i.e. they are written as they
240arrive at \b wlmscpfs, without any tag processing applied by \b wlmscpfs.
241
242Writing request files allows users to "interactively" prepare the worklist
243database (for \b wlmscpfs the worklist files served from the \e --data-file-path
244directory) by watching the request file directory.  Once a request file appears,
245one needs some time to update worklist entries in the database.  For that
246reason it makes sense to use \e --request-file-path in combination with option
247\e --sleep-before which lets users specify a certain amount of seconds that
248\b wlmscpfs should wait before actually starting to check the worklist database.
249Note that the request files written with \e --data-file-path are not
250automatically deleted by \b wlmscpfs.
251
252If request files are enabled, \b wlmscpfs must automatically create file names
253within the given directory.  By default, the format is \<timestamp\>.dump where
254\<timestamp\> is in the format YYYYMMDDhhmmssffffff where:
255- YYYY is the current year
256- MM is the current month
257- DD is the current day
258- hh are the current hours (in 24 hour format)
259- mm are the current minutes
260- ss are the current seconds and
261- ffffff is the fraction of the current second
262
263This should work as a default for most applications that would like to use
264request files and want to ensure unique file names.  If it is desired to change
265this naming scheme, the option \e --request-file-format can be used.  It
266permits to specify the file naming pattern used by \e --request-file-path.
267
268For flexibility, the following placeholders can be used in the pattern provided
269for \e --request-file-format:
270
271- \#a: calling application entity title of the peer SCU
272- \#c: called application entity title (AE title of worklist SCP application)
273- \#i: process id of the worklist SCP application process handling the request
274- \#p: patient ID if present, otherwise empty string
275- \#t: timestamp in the format YYYYMMDDhhmmssffffff
276
277The default (i.e. the value if \e --request-file-format is not explicitly set)
278is \#t.dump resulting in the timestamp format described above.
279
280An example for such a user-defined format string would be
281"request_#i_#a_#c.txt".  The \#i makes most sense if \b wlmscpfs multi-process
282mode is enabled via \e --fork option in order to ensure that simultaneous
283request will not result in the same file name for both requests.
284
285It should be noted that the \#p placeholder uses the value of Patient ID
286(0010,0020) from the request as is, i.e. if the string contains non-ASCII
287characters, the file name computed by \b wlmscpfs might be broken and thus
288cannot be written successfully or will look broken once written.  Also, an empty
289Patient ID is used as such, i.e. the \#p will be replaced with an empty string.
290
291\subsection wlmscpfs_dicom_conformance DICOM Conformance
292
293The \b wlmscpfs application supports the following SOP Classes as an SCP:
294
295\verbatim
296VerificationSOPClass                  1.2.840.10008.1.1
297FINDModalityWorklistInformationModel  1.2.840.10008.5.1.4.31
298\endverbatim
299
300The \b wlmscpfs application will accept presentation contexts for all of the
301abovementioned supported SOP Classes using any of the transfer syntaxes:
302
303\verbatim
304LittleEndianImplicitTransferSyntax    1.2.840.10008.1.2
305LittleEndianExplicitTransferSyntax    1.2.840.10008.1.2.1
306BigEndianExplicitTransferSyntax       1.2.840.10008.1.2.2
307\endverbatim
308
309The default behavior of the \b wlmscpfs application is to prefer transfer
310syntaxes having an explicit encoding over the default implicit transfer
311syntax.  If \b wlmscpfs is running on big-endian hardware it will prefer
312BigEndianExplicit to LittleEndianExplicit transfer syntax (and vice versa).
313This behavior can be changed with the \e --prefer options (see above).
314
315If compiled with zlib support enabled (see \e --version output) and if
316option \e --prefer-deflated is used, also the following transfer syntax
317is accepted.
318
319\verbatim
320DeflatedExplicitVRLittleEndianTransferSyntax  1.2.840.10008.1.2.1.99
321\endverbatim
322
323The \b wlmscpfs application does not support extended negotiation.
324
325Currently, the \b wlmscpfs application supports the following attributes as
326matching keys:
327
328\verbatim
329(0008,0020) StudyDate
330(0008,0030) StudyTime
331(0008,0050) AccessionNumber
332(0008,0090) ReferringPhysicianName
333(0010,0010) PatientName
334(0010,0020) PatientID
335(0010,0021) IssuerOfPatientID
336(0010,0030) PatientBirthDate
337(0010,0040) PatientSex
338(0010,2297) Responsible Person
339(0010,2298) Responsible Person Role
340(0032,1032) RequestingPhysician
341(0038,0010) AdmissionID
342(0040,0100) ScheduledProcedureStepSequence
343  (0008,0060) > Modality
344  (0040,0001) > ScheduledStationAETitle
345  (0040,0002) > ScheduledProcedureStepStartDate
346  (0040,0003) > ScheduledProcedureStepStartTime
347  (0040,0006) > ScheduledPerformingPhysicianName
348(0040,1001) RequestedProcedureID
349(0040,1003) RequestedProcedurePriority
350\endverbatim
351
352As return keys the following attributes are currently supported by \b wlmscpfs:
353
354\verbatim
355(0008,0020) StudyDate
356(0008,0030) StudyTime
357(0008,0050) AccessionNumber
358(0008,0080) InstitutionName
359(0008,0081) InstitutionAddress
360(0008,0090) ReferringPhysicianName
361(0008,1080) AdmittingDiagnosesDescription
362(0008,1110) ReferencedStudySequence
363  (0008,1150) > ReferencedSOPClassUID
364  (0008,1155) > ReferencedSOPInstanceUID
365(0008,1120) ReferencedPatientSequence
366  (0008,1150) > ReferencedSOPClassUID
367  (0008,1155) > ReferencedSOPInstanceUID
368(0010,0010) PatientName
369(0010,0020) PatientID
370(0010,0021) IssuerOfPatientID
371(0010,0030) PatientBirthDate
372(0010,0040) PatientSex
373(0010,1000) OtherPatientIDs (retired)
374(0010,1001) OtherPatientNames
375(0010,1020) PatientSize
376(0010,1030) PatientWeight
377(0010,1040) PatientAddress
378(0010,1080) MilitaryRank
379(0010,2000) MedicalAlerts
380(0010,2110) ContrastAllergies
381(0010,2160) EthnicGroup
382(0010,21a0) SmokingStatus
383(0010,21b0) AdditionalPatientHistory
384(0010,21c0) PregnancyStatus
385(0010,21d0) LastMenstrualDate
386(0010,2297) ResponsiblePerson
387(0010,2298) ResponsiblePersonRole
388(0010,4000) PatientComments
389(0020,000d) StudyInstanceUID
390(0032,1032) RequestingPhysician
391(0032,1033) RequestingService
392(0032,1060) RequestedProcedureDescription
393(0032,1064) RequestedProcedureCodeSequence
394  (0008,0100) > CodeValue
395  (0008,0102) > CodingSchemeDesignator
396  (0008,0103) > CodingSchemeVersion
397  (0008,0104) > CodeMeaning
398(0038,0010) AdmissionID
399(0038,0011) IssuerOfAdmissionID
400(0038,0050) SpecialNeeds
401(0038,0300) CurrentPatientLocation
402(0038,0500) PatientState
403(0040,0100) ScheduledProcedureStepSequence
404  (0008,0060) > Modality
405  (0032,1070) > RequestedContrastAgent
406  (0040,0001) > ScheduledStationAETitle
407  (0040,0002) > ScheduledProcedureStepStartDate
408  (0040,0003) > ScheduledProcedureStepStartTime
409  (0040,0004) > ScheduledProcedureStepEndDate
410  (0040,0005) > ScheduledProcedureStepEndTime
411  (0040,0006) > ScheduledPerformingPhysicianName
412  (0040,0007) > ScheduledProcedureStepDescription
413  (0040,0008) > ScheduledProtocolCodeSequence
414    (0008,0100) > > CodeValue
415    (0008,0102) > > CodingSchemeDesignator
416    (0008,0103) > > CodingSchemeVersion
417    (0008,0104) > > CodeMeaning
418  (0040,0009) > ScheduledProcedureStepID
419  (0040,0010) > ScheduledStationName
420  (0040,0011) > ScheduledProcedureStepLocation
421  (0040,0012) > PreMedication
422  (0040,0020) > ScheduledProcedureStepStatus
423  (0040,0400) > CommentsOnTheScheduledProcedureStep
424(0040,1001) RequestedProcedureID
425(0040,1002) ReasonForTheRequestedProcedure
426(0040,1003) RequestedProcedurePriority
427(0040,1004) PatientTransportArrangements
428(0040,1005) RequestedProcedureLocation
429(0040,1008) ConfidentialityCode
430(0040,1009) ReportingPriority
431(0040,1010) NamesOfIntendedRecipientsOfResults
432(0040,1400) RequestedProcedureComments
433(0040,2001) ReasonForTheImagingServiceRequest
434(0040,2004) IssueDateOfImagingServiceRequest
435(0040,2005) IssueTimeOfImagingServiceRequest
436(0040,2008) OrderEnteredBy
437(0040,2009) OrderEnterersLocation
438(0040,2010) OrderCallbackPhoneNumber
439(0040,2016) PlacerOrderNumberImagingServiceRequest
440(0040,2017) FillerOrderNumberImagingServiceRequest
441(0040,2400) ImagingServiceRequestComments
442(0040,3001) ConfidentialityConstraintOnPatientDataDescription
443\endverbatim
444
445The attribute (0008,0005) SpecificCharacterSet is a special case and its
446support by \b wlmscpfs is discussed in the NOTES section above.
447
448\subsection wlmscpfs_access_control Access Control
449
450When compiled on Unix platforms with TCP wrapper support, host-based access
451control can be enabled with the \e --access-control command line option.  In
452this case the access control rules defined in the system's host access control
453tables for \b wlmscpfs are enforced.  The default locations of the host access
454control tables are <em>/etc/hosts.allow</em> and <em>/etc/hosts.deny</em>.
455Further details are described in <b>hosts_access</b>(5).
456
457\section wlmscpfs_logging LOGGING
458
459The level of logging output of the various command line tools and underlying
460libraries can be specified by the user.  By default, only errors and warnings
461are written to the standard error stream.  Using option \e --verbose also
462informational messages like processing details are reported.  Option
463\e --debug can be used to get more details on the internal activity, e.g. for
464debugging purposes.  Other logging levels can be selected using option
465\e --log-level.  In \e --quiet mode only fatal errors are reported.  In such
466very severe error events, the application will usually terminate.  For more
467details on the different logging levels, see documentation of module "oflog".
468
469In case the logging output should be written to file (optionally with logfile
470rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
471can be used.  This configuration file also allows for directing only certain
472messages to a particular output stream and for filtering certain messages
473based on the module or application where they are generated.  An example
474configuration file is provided in <em>\<etcdir\>/logger.cfg</em>.
475
476\section wlmscpfs_command_line COMMAND LINE
477
478All command line tools use the following notation for parameters: square
479brackets enclose optional values (0-1), three trailing dots indicate that
480multiple values are allowed (1-n), a combination of both means 0 to n values.
481
482Command line options are distinguished from parameters by a leading '+' or '-'
483sign, respectively.  Usually, order and position of command line options are
484arbitrary (i.e. they can appear anywhere).  However, if options are mutually
485exclusive the rightmost appearance is used.  This behavior conforms to the
486standard evaluation rules of common Unix shells.
487
488In addition, one or more command files can be specified using an '@' sign as a
489prefix to the filename (e.g. <em>\@command.txt</em>).  Such a command argument
490is replaced by the content of the corresponding text file (multiple
491whitespaces are treated as a single separator unless they appear between two
492quotation marks) prior to any further evaluation.  Please note that a command
493file cannot contain another command file.  This simple but effective approach
494allows one to summarize common combinations of options/parameters and avoids
495longish and confusing command lines (an example is provided in file
496<em>\<datadir\>/dumppat.txt</em>).
497
498\section wlmscpfs_environment ENVIRONMENT
499
500The \b wlmscpfs utility will attempt to load DICOM data dictionaries specified
501in the \e DCMDICTPATH environment variable.  By default, i.e. if the
502\e DCMDICTPATH environment variable is not set, the file
503<em>\<datadir\>/dicom.dic</em> will be loaded unless the dictionary is built
504into the application (default for Windows).
505
506The default behavior should be preferred and the \e DCMDICTPATH environment
507variable only used when alternative data dictionaries are required.  The
508\e DCMDICTPATH environment variable has the same format as the Unix shell
509\e PATH variable in that a colon (":") separates entries.  On Windows systems,
510a semicolon (";") is used as a separator.  The data dictionary code will
511attempt to load each file specified in the \e DCMDICTPATH environment variable.
512It is an error if no data dictionary can be loaded.
513
514\section wlmscpfs_copyright COPYRIGHT
515
516Copyright (C) 1996-2020 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
517
518*/
519