Data coercion rules

 

General Syntax:

<lvalue>=<expression>

#<comment>

 

lvalues:

DICOM Tag

This is in the form, “(gggg,eeee)”. It represents the target attribute. After the expression is evaluated, the results are assigned to this attribute.

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.

 

Values

(gggg,eeee)

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 ‘\”’.

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.

(gggg,eeee),”d”,n

(Retired) This returns the nth field in the DICOM tag (gggg,eeee) value as separated by the delimiter d.

 

Functions

 

Basic Functions

<empty string>

This is the empty string, “”.

NULL()

Deletes the target lvalue.

 

Logical Functions

and(a,b)

Returns “true” if both a and b are non-NULL.

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.

 

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 integers.

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.

sub(n1,n2)

Returns the sum n1 – n2.

 

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). 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]”. Note that the line break is inserted for readability only. To work, this needs to be entered on a single line.

 

(0010,0010)=concat(split((0010,0010), ”,”, 1), “^”, split((0010,0010), ”,”, 2),

if(split((0010,0010), ”,”, 3), “^”, “”), split((0010,0010), ”,”, 3) )