DFattach
Prev 3.4. Alphabetical Listing Next

DFattach

DFattach — Attach one or more external documents to keys in a DFdiscover study

Synopsis

DFattach [-S server] [-U username] [-C password] [ [-doc docname] | [-subject # -visit # -plate # -doc docname] | [-idrf input_drf] | [-dir directory] ] [-odrf output_drf] [-log logfile] {study#}

Description

DFattach is a command-line utlity that mimics, and extends, the Plate > Attach Subject Document facility in DFexplore. It's primary function is to permit one or more documents to be attached to one or more record keys from a command-line interface.

In DFexplore, it is possible to attach a document to the current data record; using DFattach it is possible to attach documents to many records with simple commands.

Permitted document types are the same as those allowed by DFexplore.

For each document successfully attached to a key:

  • an entry is added to the system work/fax_log,

  • a DRF entry is appended to output_drf if -odrf output_drf is given as an option. The DRF entry contains 5 fields: the key of the record in the first 3 fields, the image ID assigned to the document, and the original document name.

Attaching Documents

There are 4 different methods for attaching documents.

  1. In it simplest form, DFattach attaches a single document to a single key. Specify the document with -doc docname. The key is determined from the filename of the document. The document filename must have the format subject_ visit_ plate [_other] [.extension] where subject, visit and plate are each valid, numeric identifiers for the key.

  2. Attach a single document to the key given as arguments. In this method, each of -subject # -visit # -plate # -doc docname must be explicitly specified. This has the advantage that the filename of the document to be attached does not have to change to follow a format.

  3. Read the input DRF. For each record in the DRF, the key is in the first three fields and the document name is in the fourth field. Attach the named document to the key. Repeat for each record.

  4. Process each file and subdirectory in -dir directory. For each file, if the filename has the format subject_ visit_ plate [_other] [.extension], treat the file as a document to attach to the key. Repeat for all matching files in the directory. Then recursively repeat for each sub-directory.

Permissions

Permissions are enforced for the user identified by the supplied credentials. Minimally, the user must have a study role permission that permits Server - Attach document and DFexplore - Data - Attach subject document. Additional permissions may be required dependent upon the action

Database Actions

For each document and key, [id, visit, plate], to be attached, the steps are:

  1. Confirm that the combination of visit and plate are defined in the visit map. If it is not, output an error message and skip this document.

  2. Lock the key. If the key cannot be locked, output an error message and skip this document.

  3. If the key does not exist in the database, a record with pending status is created. The document becomes the primary image. Create Data permission is required.

  4. If the key matches an existing missed record, the missed record is deleted and a record with pending status is created. The document becomes the primary image. Delete Missed record and Create Data permission are required.

  5. If the key exists, and there is already a primary image, the document is attached as a secondary image; otherwise, the document is attached as the primary image. Modify Data permission is required.

Options

-S server

DFdiscover server name

-U username

DFdiscover login username

-C password

login password. Refer to Section 3.2, “User Credentials” for recommended/better solutions for safe password handling.

-doc docname

determine the key encoded in docname and attach docname to that key

-subject # -visit # -plate # -doc docname

attach docname to the given key

-idrf input_drf

read input_drf, which is in DRF format, and for each record add the document to the given key

-dir directory

read directory and recursively each sub-directory, and for each filename that matches the required pattern attach filename to the given key

-odrf output_drf

for each document that is successfully attached, append a DRF record to output_drf. Subsequently a task can be built from the DRF to review the attached documents.

-log logfile

write any log messages to logfile

study#

the study number where the documents are to be attached; required

Exit Status

DFattach exits with one of the following statuses:

0

The command is successful.

1

One or more errors occurred, and the command has failed. Error messages are written to standard error on the command-line.

Examples

In each of the following examples, the options -S server, -U username and -C password are not shown but are required.

Example 3.4. Attach 1234_1_12.pdf to subject 1234, visit 1, plate 12 in the database for study 100 

% DFattach -doc 1234_1_12.pdf 100

Example 3.5. Attach radiograph.pdf to subject 30001, visit 10, plate 200 in the database for study 22 

% DFattach -subject 30001 -visit 10 -plate 200 -doc radiograph.pdf 22

Example 3.6. Attach all of the documents in directory /tmp/newdocs to the matching keys in study 200 and record the successes in /tmp/results.drf 

% ls /tmp/newdocs
250001_0_1.pdf
250002_0_1.pdf
350001_0_1.pdf
350001_0_2.pdf
350001_1_10.pdf
% DFattach -dir /tmp/newdocs -odrf /tmp/results.drf 200

Prev Up Next
DFaccess.rpc Home DFaudittrace