1wlmscpfs(1)                       OFFIS DCMTK                      wlmscpfs(1)
2
3
4

NAME

6       wlmscpfs - DICOM Basic Worklist Management SCP (based on data files)
7
8

SYNOPSIS

10       wlmscpfs [options] port
11

DESCRIPTION

13       The  wlmscpfs application implements a Service Class Provider (SCP) for
14       the Basic Worklist Management Service. The application will listen on a
15       specified TCP/IP port for incoming association requests from a Worklist
16       Management SCU. In case an association was acknowledged and a  worklist
17       query  was  received,  the  wlmscpfs  application will query particular
18       files  in  a  certain  directory  (which  can  be   specified   through
19       corresponding  program  options)  on  the file system for corresponding
20       worklist information, and it will send this  information  back  to  the
21       calling  Worklist  Management  SCU.  Aside  from  dealing with Worklist
22       Management  queries,  the  wlmscpfs  application  also   supports   the
23       Verification Service Class as an SCP.
24

PARAMETERS

26       port  tcp/ip port number to listen on
27

OPTIONS

29   general options
30         -h    --help
31                 print this help text and exit
32
33               --version
34                 print version information and exit
35
36               --arguments
37                 print expanded command line arguments
38
39         -q    --quiet
40                 quiet mode, print no warnings and errors
41
42         -v    --verbose
43                 verbose mode, print processing details
44
45         -d    --debug
46                 debug mode, print debug information
47
48         -ll   --log-level  [l]evel: string constant
49                 (fatal, error, warn, info, debug, trace)
50                 use level l for the logger
51
52         -lc   --log-config  [f]ilename: string
53                 use config file f for the logger
54
55   multi-process options
56         -s    --single-process
57                 single process mode
58
59               --fork
60                 fork child process for each association (default)
61
62   input options
63       general:
64
65         -dfp  --data-files-path  [p]ath: string (default: .)
66                 path to worklist data files
67
68       handling of worklist files:
69
70         -efr  --enable-file-reject
71                 enable rejection of incomplete worklist files (default)
72
73         -dfr  --disable-file-reject
74                 disable rejection of incomplete worklist files
75
76   processing options
77       returned character set:
78
79         -cs0  --return-no-char-set
80                 return no specific character set (default)
81
82         -cs1  --return-iso-ir-100
83                 return specific character set ISO IR 100
84
85         -csk  --keep-char-set
86                 return character set provided in file
87
88       other processing options:
89
90         -nse  --no-sq-expansion
91                 disable expansion of empty sequences in C-FIND
92                 request messages
93
94   network options
95       preferred network transfer syntaxes:
96
97         +x=   --prefer-uncompr
98                 prefer explicit VR local byte order (default)
99
100         +xe   --prefer-little
101                 prefer explicit VR little endian TS
102
103         +xb   --prefer-big
104                 prefer explicit VR big endian TS
105
106         +xd   --prefer-deflated
107                 prefer deflated explicit VR little endian TS
108
109         +xi   --implicit
110                 accept implicit VR little endian TS only
111
112       network host access control (tcp wrapper):
113
114         -ac   --access-full
115                 accept connections from any host (default)
116
117         +ac   --access-control
118                 enforce host access control rules
119
120       post-1993 value representations:
121
122         +u    --enable-new-vr
123                 enable support for new VRs (UN/UT) (default)
124
125         -u    --disable-new-vr
126                 disable support for new VRs, convert to OB
127
128       deflate compression level (only with --prefer-deflated):
129
130         +cl   --compression-level  [l]evel: integer (default: 6)
131                 0=uncompressed, 1=fastest, 9=best compression
132
133       other network options:
134
135         -ta   --acse-timeout  [s]econds: integer (default: 30)
136                 timeout for ACSE messages
137
138         -td   --dimse-timeout  [s]econds: integer (default: unlimited)
139                 timeout for DIMSE messages
140
141               --max-associations  [a]ssocs: integer (default: 50)
142                 limit maximum number of parallel associations
143
144               --refuse
145                 refuse association
146
147               --reject
148                 reject association if no implementation class UID
149
150               --no-fail
151                 don't fail on an invalid query
152
153               --sleep-before  [s]econds: integer
154                 sleep s seconds before find (default: 0)
155
156               --sleep-after  [s]econds: integer
157                 sleep s seconds after find (default: 0)
158
159               --sleep-during  [s]econds: integer
160                 sleep s seconds during find (default: 0)
161
162         -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
163                 set max receive pdu to n bytes (default: 16384)
164
165         -dhl  --disable-host-lookup
166                 disable hostname lookup
167
168   output options
169       general:
170
171         -rfp  --request-file-path  [p]ath: string
172                 path to store request files to
173
174         -rff  --request-file-format  [f]ormat: string (default: #t.dump)
175                 request file name format
176

NOTES

178       The  semantic  impacts  of the above mentioned options is clear for the
179       majority of options. Some particular options, however, are so  specific
180       that  they  need  detailed  descriptions  which  will  be given in this
181       passage.
182
183       The returned character set options are intended for situations in which
184       the  wlmscpfs  application  will  return attribute values which are not
185       composed of characters from the DICOM default character repertoire.  In
186       such  cases,  for  example  option  --return-iso-ir-100  can be used to
187       specify that a response to  a  modality's  worklist  management  C-FIND
188       request   shall   contain  DICOM's  Specific  Character  Set  attribute
189       (0008,0005)  with  a  corresponding  value,  indicating  the  character
190       repertoire  from which the characters of returned attribute values were
191       taken (in this example the repertoire ISO IR 100). Please note that the
192       wlmscpfs  application  will  not make sure that all returned values are
193       actually made up of this character repertoire; the application  expects
194       this to be the case.
195
196       In  general, the Specific Character Set attribute (0008,0005) will only
197       be included in the C-FIND response if it contains any  attributes  that
198       are  affected  by the character set, i.e. for value representations PN,
199       LO, LT, SH, ST and UT.
200
201       Please note that a C-FIND request which is handled by this  application
202       may  contain  DICOM's Specific Character Set attribute (0008,0005), but
203       this application will never use this attribute's  value  for  matching.
204       Besides,  the  question  if  DICOM's  Specific  Character Set attribute
205       (0008,0005) will be contained in a C-FIND response which is returned by
206       this  application  is  always  determined by the returned character set
207       option which was specified when this application was started.
208
209       The options --enable-file-reject and --disable-file-reject can be  used
210       to  enable  or disable a file rejection mechanism which makes sure only
211       complete worklist files will be used during  the  matching  process.  A
212       worklist file is considered to be complete if it contains all necessary
213       type 1 information which the SCP might have to return to an SCU in a C-
214       FIND  response  message.  Table  K.6-1  in  part 4 annex K of the DICOM
215       standard lists all corresponding type 1 attributes (see column  'Return
216       Key Type').
217
218   Writing Request Files
219       Providing option --request-file-path enables writing of the incoming C-
220       FIND requests into text files. The option  value  provides  the  target
221       directory  where  these  files  will  be  stored. All request files are
222       stored in 'dump' format as provided by the dcmdump tool  and  are  raw,
223       i.e.  they  are  written  as  they  arrive at wlmscpfs, without any tag
224       processing applied by wlmscpfs.
225
226       Writing request files  allows  users  to  'interactively'  prepare  the
227       worklist  database  (for  wlmscpfs  the  worklist files served from the
228       --data-file-path directory) by watching  the  request  file  directory.
229       Once  a  request  file  appears, one needs some time to update worklist
230       entries in the  database.  For  that  reason  it  makes  sense  to  use
231       --request-file-path  in  combination  with  option --sleep-before which
232       lets users specify a certain amount of  seconds  that  wlmscpfs  should
233       wait before actually starting to check the worklist database. Note that
234       the request files written with --data-file-path are  not  automatically
235       deleted by wlmscpfs.
236
237       If  request  files are enabled, wlmscpfs must automatically create file
238       names  within  the  given  directory.  By  default,   the   format   is
239       <timestamp>.dump     where     <timestamp>    is    in    the    format
240       YYYYMMDDhhmmssffffff where:
241
242       • YYYY is the current year
243
244       • MM is the current month
245
246       • DD is the current day
247
248       • hh are the current hours (in 24 hour format)
249
250       • mm are the current minutes
251
252       • ss are the current seconds and
253
254       • ffffff is the fraction of the current second
255
256       This should work as a default for most applications that would like  to
257       use  request  files  and  want  to  ensure  unique file names. If it is
258       desired to change this naming scheme, the option  --request-file-format
259       can  be used. It permits one to specify the file naming pattern used by
260       --request-file-path.
261
262       For flexibility, the following placeholders can be used in the  pattern
263       provided for --request-file-format:
264
265       • #a: calling application entity title of the peer SCU
266
267       • #c:  called  application  entity  title  (AE  title  of  worklist SCP
268         application)
269
270       • #i: process id of the worklist SCP application process  handling  the
271         request
272
273       • #p: patient ID if present, otherwise empty string
274
275       • #t: timestamp in the format YYYYMMDDhhmmssffffff
276
277       The  default (i.e. the value if --request-file-format is not explicitly
278       set) is #t.dump resulting in the timestamp format described above.
279
280       An  example  for  such  a   user-defined   format   string   would   be
281       'request_#i_#a_#c.txt'.  The  #i  makes  most  sense if wlmscpfs multi-
282       process mode is enabled via --fork  option  in  order  to  ensure  that
283       simultaneous  request  will  not  result in the same file name for both
284       requests.
285
286       It should be noted that the #p placeholder uses the value of Patient ID
287       (0010,0020)  from  the  request as is, i.e. if the string contains non-
288       ASCII characters, the file name computed by wlmscpfs  might  be  broken
289       and  thus  cannot  be  written  successfully  or  will look broken once
290       written. Also, an empty Patient ID is used as such, i.e. the #p will be
291       replaced with an empty string.
292
293   DICOM Conformance
294       The wlmscpfs application supports the following SOP Classes as an SCP:
295
296       VerificationSOPClass                  1.2.840.10008.1.1
297       FINDModalityWorklistInformationModel  1.2.840.10008.5.1.4.31
298
299       The  wlmscpfs  application will accept presentation contexts for all of
300       the abovementioned supported SOP Classes  using  any  of  the  transfer
301       syntaxes:
302
303       LittleEndianImplicitTransferSyntax    1.2.840.10008.1.2
304       LittleEndianExplicitTransferSyntax    1.2.840.10008.1.2.1
305       BigEndianExplicitTransferSyntax       1.2.840.10008.1.2.2
306
307       The  default behavior of the wlmscpfs application is to prefer transfer
308       syntaxes having an explicit encoding over the default implicit transfer
309       syntax.  If  wlmscpfs  is running on big-endian hardware it will prefer
310       BigEndianExplicit to LittleEndianExplicit  transfer  syntax  (and  vice
311       versa).  This  behavior  can  be changed with the --prefer options (see
312       above).
313
314       If compiled with zlib support enabled (see  --version  output)  and  if
315       option --prefer-deflated is used, also the following transfer syntax is
316       accepted.
317
318       DeflatedExplicitVRLittleEndianTransferSyntax  1.2.840.10008.1.2.1.99
319
320       The wlmscpfs application does not support extended negotiation.
321
322       Currently, the wlmscpfs application supports the  following  attributes
323       as matching keys:
324
325       (0008,0020) StudyDate
326       (0008,0030) StudyTime
327       (0008,0050) AccessionNumber
328       (0008,0090) ReferringPhysicianName
329       (0010,0010) PatientName
330       (0010,0020) PatientID
331       (0010,0021) IssuerOfPatientID
332       (0010,0030) PatientBirthDate
333       (0010,0040) PatientSex
334       (0010,2297) Responsible Person
335       (0010,2298) Responsible Person Role
336       (0032,1032) RequestingPhysician
337       (0038,0010) AdmissionID
338       (0040,0100) ScheduledProcedureStepSequence
339         (0008,0060) > Modality
340         (0040,0001) > ScheduledStationAETitle
341         (0040,0002) > ScheduledProcedureStepStartDate
342         (0040,0003) > ScheduledProcedureStepStartTime
343         (0040,0006) > ScheduledPerformingPhysicianName
344       (0040,1001) RequestedProcedureID
345       (0040,1003) RequestedProcedurePriority
346
347       As  return  keys  the  following  attributes are currently supported by
348       wlmscpfs:
349
350       (0008,0020) StudyDate
351       (0008,0030) StudyTime
352       (0008,0050) AccessionNumber
353       (0008,0080) InstitutionName
354       (0008,0081) InstitutionAddress
355       (0008,0090) ReferringPhysicianName
356       (0008,1080) AdmittingDiagnosesDescription
357       (0008,1110) ReferencedStudySequence
358         (0008,1150) > ReferencedSOPClassUID
359         (0008,1155) > ReferencedSOPInstanceUID
360       (0008,1120) ReferencedPatientSequence
361         (0008,1150) > ReferencedSOPClassUID
362         (0008,1155) > ReferencedSOPInstanceUID
363       (0010,0010) PatientName
364       (0010,0020) PatientID
365       (0010,0021) IssuerOfPatientID
366       (0010,0030) PatientBirthDate
367       (0010,0040) PatientSex
368       (0010,1000) OtherPatientIDs (retired)
369       (0010,1001) OtherPatientNames
370       (0010,1020) PatientSize
371       (0010,1030) PatientWeight
372       (0010,1040) PatientAddress
373       (0010,1080) MilitaryRank
374       (0010,2000) MedicalAlerts
375       (0010,2110) ContrastAllergies
376       (0010,2160) EthnicGroup
377       (0010,21a0) SmokingStatus
378       (0010,21b0) AdditionalPatientHistory
379       (0010,21c0) PregnancyStatus
380       (0010,21d0) LastMenstrualDate
381       (0010,2297) ResponsiblePerson
382       (0010,2298) ResponsiblePersonRole
383       (0010,4000) PatientComments
384       (0020,000d) StudyInstanceUID
385       (0032,1032) RequestingPhysician
386       (0032,1033) RequestingService
387       (0032,1060) RequestedProcedureDescription
388       (0032,1064) RequestedProcedureCodeSequence
389         (0008,0100) > CodeValue
390         (0008,0102) > CodingSchemeDesignator
391         (0008,0103) > CodingSchemeVersion
392         (0008,0104) > CodeMeaning
393       (0038,0010) AdmissionID
394       (0038,0011) IssuerOfAdmissionID
395       (0038,0050) SpecialNeeds
396       (0038,0300) CurrentPatientLocation
397       (0038,0500) PatientState
398       (0040,0100) ScheduledProcedureStepSequence
399         (0008,0060) > Modality
400         (0032,1070) > RequestedContrastAgent
401         (0040,0001) > ScheduledStationAETitle
402         (0040,0002) > ScheduledProcedureStepStartDate
403         (0040,0003) > ScheduledProcedureStepStartTime
404         (0040,0004) > ScheduledProcedureStepEndDate
405         (0040,0005) > ScheduledProcedureStepEndTime
406         (0040,0006) > ScheduledPerformingPhysicianName
407         (0040,0007) > ScheduledProcedureStepDescription
408         (0040,0008) > ScheduledProtocolCodeSequence
409           (0008,0100) > > CodeValue
410           (0008,0102) > > CodingSchemeDesignator
411           (0008,0103) > > CodingSchemeVersion
412           (0008,0104) > > CodeMeaning
413         (0040,0009) > ScheduledProcedureStepID
414         (0040,0010) > ScheduledStationName
415         (0040,0011) > ScheduledProcedureStepLocation
416         (0040,0012) > PreMedication
417         (0040,0020) > ScheduledProcedureStepStatus
418         (0040,0400) > CommentsOnTheScheduledProcedureStep
419       (0040,1001) RequestedProcedureID
420       (0040,1002) ReasonForTheRequestedProcedure
421       (0040,1003) RequestedProcedurePriority
422       (0040,1004) PatientTransportArrangements
423       (0040,1005) RequestedProcedureLocation
424       (0040,1008) ConfidentialityCode
425       (0040,1009) ReportingPriority
426       (0040,1010) NamesOfIntendedRecipientsOfResults
427       (0040,1400) RequestedProcedureComments
428       (0040,2001) ReasonForTheImagingServiceRequest
429       (0040,2004) IssueDateOfImagingServiceRequest
430       (0040,2005) IssueTimeOfImagingServiceRequest
431       (0040,2008) OrderEnteredBy
432       (0040,2009) OrderEnterersLocation
433       (0040,2010) OrderCallbackPhoneNumber
434       (0040,2016) PlacerOrderNumberImagingServiceRequest
435       (0040,2017) FillerOrderNumberImagingServiceRequest
436       (0040,2400) ImagingServiceRequestComments
437       (0040,3001) ConfidentialityConstraintOnPatientDataDescription
438
439       The attribute (0008,0005) SpecificCharacterSet is a  special  case  and
440       its support by wlmscpfs is discussed in the NOTES section above.
441
442   Access Control
443       When  compiled  on  Unix platforms with TCP wrapper support, host-based
444       access control can be enabled with the  --access-control  command  line
445       option.  In  this case the access control rules defined in the system's
446       host access control tables  for  wlmscpfs  are  enforced.  The  default
447       locations  of  the  host access control tables are /etc/hosts.allow and
448       /etc/hosts.deny. Further details are described in hosts_access(5).
449

LOGGING

451       The level of logging output of  the  various  command  line  tools  and
452       underlying  libraries  can  be  specified by the user. By default, only
453       errors and warnings are written to the  standard  error  stream.  Using
454       option  --verbose  also  informational messages like processing details
455       are reported. Option --debug can be used to get  more  details  on  the
456       internal  activity,  e.g.  for debugging purposes. Other logging levels
457       can be selected using option --log-level. In --quiet  mode  only  fatal
458       errors  are reported. In such very severe error events, the application
459       will usually terminate. For  more  details  on  the  different  logging
460       levels, see documentation of module 'oflog'.
461
462       In  case  the logging output should be written to file (optionally with
463       logfile rotation), to syslog (Unix) or the event log  (Windows)  option
464       --log-config  can  be  used.  This  configuration  file also allows for
465       directing only certain messages to a particular output stream  and  for
466       filtering  certain  messages  based  on the module or application where
467       they are generated.  An  example  configuration  file  is  provided  in
468       <etcdir>/logger.cfg.
469

COMMAND LINE

471       All  command  line  tools  use  the  following notation for parameters:
472       square brackets enclose optional  values  (0-1),  three  trailing  dots
473       indicate  that multiple values are allowed (1-n), a combination of both
474       means 0 to n values.
475
476       Command line options are distinguished from parameters by a leading '+'
477       or  '-' sign, respectively. Usually, order and position of command line
478       options are arbitrary (i.e. they  can  appear  anywhere).  However,  if
479       options  are  mutually exclusive the rightmost appearance is used. This
480       behavior conforms to the  standard  evaluation  rules  of  common  Unix
481       shells.
482
483       In  addition,  one  or more command files can be specified using an '@'
484       sign as a prefix to the filename (e.g. @command.txt).  Such  a  command
485       argument  is  replaced  by  the  content of the corresponding text file
486       (multiple whitespaces are treated as a  single  separator  unless  they
487       appear  between  two  quotation marks) prior to any further evaluation.
488       Please note that a command file cannot contain  another  command  file.
489       This  simple  but  effective  approach  allows  one to summarize common
490       combinations of options/parameters and  avoids  longish  and  confusing
491       command lines (an example is provided in file <datadir>/dumppat.txt).
492

ENVIRONMENT

494       The  wlmscpfs  utility  will  attempt  to  load DICOM data dictionaries
495       specified in the DCMDICTPATH environment variable. By default, i.e.  if
496       the   DCMDICTPATH   environment   variable   is   not   set,  the  file
497       <datadir>/dicom.dic will be loaded unless the dictionary is built  into
498       the application (default for Windows).
499
500       The   default   behavior   should  be  preferred  and  the  DCMDICTPATH
501       environment variable only used when alternative data  dictionaries  are
502       required.  The  DCMDICTPATH environment variable has the same format as
503       the Unix shell PATH variable in that a colon (':')  separates  entries.
504       On  Windows systems, a semicolon (';') is used as a separator. The data
505       dictionary code will  attempt  to  load  each  file  specified  in  the
506       DCMDICTPATH  environment variable. It is an error if no data dictionary
507       can be loaded.
508
510       Copyright (C) 1996-2022 by OFFIS e.V., Escherweg  2,  26121  Oldenburg,
511       Germany.
512
513
514
515Version 3.6.7                   Fri Apr 22 2022                    wlmscpfs(1)
Impressum