The PACS Server
The PACS Server
The general encoding rules for coercion commands is as follows:
| Type | Description |
| gTag | The first part of a DICOM tag representing the attribute group. Expressed as four hex digits. |
| eTag | The second part of a DICOM tag representing the attribute element. Expressed as four hex digits. |
| Integer | Numeric value used and returned in some expression functions, including arithmetic functions. |
| String | Group of ASCII-numeric and control characters. When non-contiguous, strings must be encapsulated within double quotes (""). Control characters must be preceded by a backslash, as in "\n", "\\" and "\"". |
| Variable | Description |
| $(varName) | A temporary variable used to hold an evaluated expression for reuse in a later rule. Temporary values are not stored in the object. Temporary variables can appear either as lvalues or in expressions. See the lvalue and value sections for temporary variable syntax. |
| $(@PROCESS) | A control variable that controls whether processing the object continues or not. By default, this control variable evaluates to "true" (not NULL()). If the control variable is set to false (NULL()), processing the object stops. If the control variable evaluates to true, then processing continues. When used in actions, this control variable can be used to stop the storing, forwarding, editing, etc., of the object. Example: if the SOP class is Digital Mammography X-Ray Image Storage - For Processing, set the processing flag to false to stop processing this object. Otherwise, continue processing keeps its previous value (which is true by default). $(@PROCESS)=if(equals((0008,0016), "1.2.840.10008.5.1.4.1.1.1.2.1"), NULL(), $(@PROCESS)) |
| $(@STUDYLEVELCOMMANDS) | A control variable that can be assigned a viewer macro command, which is executed when the defined trigger event occurs. Available macros and their parameters are defined in the Viewer Macros section below. |
|
Variable |
Description |
| SetDropXML(T,S,E) | Submits the study or studies identifier, S, to the engine, E, when the trigger event, T, occurs. These macros are in addition to hard-configured XML file drop settings. If the viewer coercion rule applies to the same engine as a hard-configured rule, only one XML file is dropped and it complies with the coercion rule. However, defining multiple macros for the same trigger with different engines, whether they are coercion rule macros or hard-configured XML file drop settings, a file is dropped for each engine.. The parameters are defined as follows: Trigger: "StudyOpen", "Dictation", "StudyClose" Study: A single study UID string (drop an XML file for this study only), an empty string (override the hard-configured XML file drop rule), or "all" (drop an XML file for any study) Engine: The engine's name (label) as defined in the XML file drop configuration file. Example: Define a SetDropXML macro in the viewer that will drop the XML file defined for ReportingSystem in the XML File Drop configuration file when the viewer opens the study defined by (0020,000D). The macro will be: SetDropXML( "StudyOpen", "1.1.1.1.1.1.1", "ReportingSystem"); if the study uid is "1.1.1.1.1.1.1")$(@STUDYLEVELCOMMANDS)=concat("SetDropXML(\"StudyOpen\", \"",(0020,000d),"\", \"ReportingSystem\");") |
| Ivalue | Description |
| (gTag,eTag) | DICOM attribute tag. The parentheses are required. After the expression is evaluated, the results are assigned to this attribute. |
| SEQ(gTag1,eTag1, INo1,gTag2,eTag2 [,INo2,gTag3,eTag3...]) | A DICOM sequence attribute. Specified by Tag2 within the INo item in the sequence specified by Tag1, where 0 represents the first item in the sequence. If the sequence Tag1 does not exist in the object, the entire expression is ignored. |
| USER(fieldName) | Custom database fields in the form USER(fieldName) where fieldName is the Field Name defined in the database configuration file dcfields.conf. Custom database fields are valid on the left and right side of assignments. |
| $(varName) | Temporary variable in the form $(varName) where varName is a unique string used to identify the variable. |
| Value | Description |
| (gTag,eTag) | This returns the value of a DICOM tag. If the DICOM tag does not exist, NULL() is returned. The parentheses are required. |
| Quoted string | This is in the form, “<string>”. Returns the literal string <string>. The string can contain escaped characters, including “\n”, “\\” and ‘\”’. |
| SEQ(gTag1,eTag1, INo1,gTag2,eTag2 [,INo2,gTag3,eTag3...]) |
Returns the contents of the DICOM attribute specified by Tag2 within the sequence specified by Tag1. INo indicates the sequence item instance, where 0 represents the first item in the sequence. Returns NULL() if the attribute does not exist in the INo item of the sequence. |
| Unquoted string | Non-quoted strings can be used when they contain only contiguous, alphanumeric characters. |
| USER(fieldName) | Custom database field in the form USER(fieldName) where fieldName is the Field Name defined in the database configuration file dcfields.conf. |
| $(varName) | Temporary variable in the form $(varName) where varName is a unique string used to identify the variable. Uninitialized temporary values return NULL. |
| (gTag,eTag),”d”,n | (Retired) This returns the nth field in the DICOM tag (gggg,eeee) value as separated by the delimiter d. |
| Function | Description |
| add(n1,n2[,n3…]) | Returns the sum of the integers. |
| and(a,b) | Return “true” if both a and b are non-NULL. |
| between(n,min,max) | Returns true if integer string n is greater than or equal to min and less than max. Otherwise, it returns NULL. |
| codenumber(n) | Returns a coded numeric string based on n. Both n and the result are ascii numeric strings >= 0. Result contains the same number of digits as in n. |
| codestring(s[,x]) | Returns a coded string based on the string s. Characters in string x, if present, shall not exist in the result. |
| concat(a,b[,c…]) | Concatenate the values a and b (and c, etc.) NULL values are treated as an empty string, “”. |
| contains(a,b) | Return b if string b exists in string a. Otherwise it returns NULL. |
| dicomAge(d1,d2) | Returns the value d1 - d2 in calendar years, months or days in DICOMcompliant format: nnnY, nnnM, or nnnD. If either d1 or d2 is an invalid date value, or d2 predates d1, NULL is returned. |
| <empty string> | This is the empty string, “”. |
| equals(a,b) | Return “true” if a and b are equal, NULL if they are not equal. |
| if(cond,a,b) | Return a if cond is not NULL, b if cond is NULL. |
| indexof(a, p) | Return the starting position of pattern p in string a. The first position in string a is 0. Returns -1 if p is not found in a. Returns NULL if p or a is NULL. |
| not(a) | Return “true” if a is NULL, NULL if a is not NULL. |
| NULL() | Delete the target lvalue. |
| or(a,b[,c...]) | Return the first non-NULL value. |
| rnd(n[,seed]) |
Returns a random number string based on seed, if present, between 0 and n-1. |
| split(a,d,n) | Return the nth field in a using d as the field delimiter. |
| strlen(a) |
Return the number of characters in string a, or NULL if string a is NULL. |
| sub(n1,n2) | Returns the sum n1 – n2. |
| div(n1,n2) |
Divide the operands using integer division, n1/n2. Operands must be Number types. Division by zero is checked, but zero-value denominators will return an error. |
| mul(n1,n2[,n3...]) | Multiply all operands. Operands must be Number types. |
| substr(a,from[,len]) | Return the len characters in a, starting at position from. The first position is ‘0’. If from extends past the end of the string, the NULL string is returned. If len is omitted, the remaining string is returned. |
| translate(a,d,i1,o1 [,i2,o2...]) | Returns the output value, oN, if the input string, iN, matches the source string, a. If the source string matches no input string, the function returns the default value, d. Source string, a, and input strings, iN, must be String types or NULL(). The default value, d, and output values, oN, can be any type but must all be of the same type. |
| mod(n1,n2) |
Return the remainder of the integer division, n1/n2. Operands must be Number types. Division by zero is checked, but zero-value denominators will return an error. |
| toLower(a) | Returns the string, a, with all letters converted to lower case. |
| toUpper(a) | Returns the string, a, with all letters converted to upper case. |
Note: In the evaluation of expressions, NULL is not the same as the empty string, “”. If a DICOM attribute does not exist, it is NULL. If it exists, but contains a 0-length value, it is the empty string, “”.
An example of a coercion rule:
An example of translating a string of defined values to an enumerated set of values for conventional or space-saving purposes, such as in mammography view positions, might look like the following. It converts "cranio-caudal" to "CC" and "medio-lateral oblique" to "MLO", and assigns the abbreviated value to the Series Description attribute. In this example, the view code value is obtained from the first sequence item in the View Code Sequence (0054,0220).
(0008,103e)=translate( SEQ(0054,0220,0,0008,0104), SEQ(0054,0220,0,0008,0104), "cranio-caudal", "CC", "medio-lateral oblique", "MLO" )
Note: Line breaks in each example are inserted for readability only. To work, these commands must be entered on a single line.
To swap two values, define a three-step process:
The coercion rules manual is available for download.