General Syntax:
<lvalue>=<expression>
#<comment>
Data Types
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 "\"". |
Number |
Integer value used and returned in arithmetic functions. |
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. |
lvalues:
(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 target 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 rule is ignored. |
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. |
Expressions: Can be either a Value or a Function.
Expression Values
(gTag,eTag)
|
DICOM attribute tag. The parentheses are required. Returns the value of a DICOM tag. If the DICOM tag does not exist, NULL() is returned. |
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. |
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. |
Expression Functions
Basic Functions
"" |
The empty string. An existing string of zero length. |
NULL() |
The non-existent state. When assigned, it deletes the target lvalue. |
Logic Functions
and(a,b) |
Returns "true" if both a and b are non-NULL. |
between(n,min,max) |
Returns "true" if n is greater than or equal to min and less than max. Otherwise, it returns NULL. Operands must be Number types. |
equals(a,b) |
Returns "true" if a and b are equal, NULL if they are not equal. |
if(cond,a,b) |
Returns a if cond is not NULL, b if cond is NULL. |
not(a) |
Returns "true" if a is NULL, NULL() if a is not NULL. |
or(a,b[,c...]) |
Returns the first non-NULL value. |
String Functions
concat(a,b[,c...]) |
Concatenates the values a and b (and c, etc.) NULL values are treated as an empty string, "". |
contains(a,b) |
Returns string b if string b exists in string a. Otherwise it returns NULL. |
indexof(a, p) |
Returns 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. |
split(a,d,n) |
Returns the nth field in a using d as the field delimiter. |
strlen(a) |
Returns the number of characters in string a, or NULL if string a is NULL. |
substr(a,from[,len]) |
Returns 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. |
Date Functions
dicomAge(d1,d2) |
Returns the value d1 - d2 in calendar years, months or days in DICOM-compliant format: nnnY, nnnM, or nnnD. If either d1 or d2 is an invalid date value, or d2 predates d1, NULL is returned. |
Arithmetic Functions
add(n1,n2[,n3...]) |
Returns the sum of the operands. Operands must be Number types. |
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. |
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. |
sub(n1,n2) |
Returns the difference, n1-n2. All operands must be Number types. |
Encoding Functions
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. |
rnd(n[,seed]) |
Returns a random number string based on seed, if present, between 0 and n-1. |
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 to insert a prefix, "PFX", before the Accession Number (0008,0050) is below. If the attribute 0008,0050 exists, even if it contains a 0-length value, insert "PFX" into the beginning of the existing value and assign it back to the original attribute. If the original attribute does not exist, return NULL(), which prevents it from being added to the object.
(0008,0050)=if( (0008,0050) , concat("PFX",(0008,0050)) , NULL() )
Another example is to coerce a patient name, (0010,0010), defined as "LASTNAME,FIRSTNAME[,MI]" into DICOM-compliant syntax, "LASTNAME^FIRSTNAME[^MI]".
(0010,0010)=concat(split((0010,0010), ",", 1), "^", split((0010,0010), ",", 2),
if(split((0010,0010), ",", 3), "^", ""), split((0010,0010), ",", 3)
)
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: that the line breaks in each example are inserted for readability only. To work, these commands must be entered on a single line.