DFpdf
DFpdf — Generate bookmarked PDF documents of CRF images
Synopsis
DFpdf
[
[-c password]
| [-C]
]
[-d]
[-i string]
[-o string]
[-f string]
[-v string]
[-g string]
[-s string]
[-t string]
[-j string]
[-k string]
[-n]
[-b string
[-a string]
[-m #]
]
{#}
Description
DFpdf generates an optionally password-protected PDF document containing one or more pages, where each page is a study CRF, bookmarked within the complete PDF. The resulting PDF document follows the Adobe PDF specification, version 1.4.
If a password is provided, the entire file is encrypted and stored in binary format. Otherwise, the file is stored in plain text format.
DFpdf requires a study number argument and an input file. The input file, which
must be in either DFdiscover data export or DRF format, lists the images that are
to be included in the PDF output document. Sort order in the output
matches the order that records appear in the input file.
If the -s option is
specified, sort order
within subject will follow the rules specified by the contents of
sortmapsortmap.
Bookmarks are created at the document root, subject, visit, and plate levels.
The label for the document root bookmark is ID, Visit, Plate
but can be
over-ridden through the use of -t. A new bookmark
is created as each new ID is encountered in the input and the label is of the
form ID .
A visit bookmark is created for each new visit number
within the current ID. The label is created from
field 3 of the study visit map
if the visit is defined in the visit map; otherwise,
it has the form #####Visit .
Finally, a plate bookmark is created for each CRF in the input file.
The label is created from the matching page map entry, if it is defined;
from field 2 of the study #####DFfile_map if the plate is defined
(which it should always be); or, it has the form
Plate .
For secondary records, an asterisk
(#####*) is appended to the end of the page bookmark label. Hence it is easy to
scan the list of expanded bookmarks and identify those records that are
secondaries.
Using the -j and -k options, custom page
header and footer labels, respectively, can be created for each CRF page
in the output document.
If no labels are specified, the default header label is
ID %DFID : %DFPMLBL and there is no footer label.
The desired label is specified in a string
[11]
and may contain any combination
of fixed text and zero or more of the following keywords, which are
replaced at output creation time with the matching database value:
%DFSTATUS- record status (the status label is returned, rather than the status number)%DFVALID- record validation level%DFRASTER- image ID%DFSTUDY- DFdiscover study number%DFPLATE- plate number%DFSEQ- visit or sequence number%DFID- subject ID%DFCREATE- record creation time stamp%DFMODIFY- record modification time stamp%DFPMLBL- page map label for the current keys as defined inDFpage_map%DFVLBL- visit label for the current keys as defined inDFvisit_map%DFPLBL- plate label for the current keys as defined inDFschema
A warning message is written to stderr for each record in the input file that does not reference an image file. No output is written to the PDF file for such records.
For records exported from the new fax queue, bookmarking will only be as good as the accuracy of the ICR on the record keys.
It is possible to override the default labeling for study visits and plates
by providing alternative visit map, file map, and page map files with the
-v, -f, and -g
options respectively.
![[Note]](../../imagedata/note.png) | PDF document size |
|---|---|
|
The output PDF document contains copies of the CRF images and hence each file can be quite large. The images are compressed so that the space requirements are not as onerous as for the source CRF images, but still, an input file listing 500 CRF images will create a PDF document that is approximately 5MB in size. |
DFpdf exits with a status 0 if a PDF output file was successfully created; otherwise, a non-zero exit status is returned.
Options
-c password, -C |
If
The password file |
-d | the input file is in DFdiscover Retrieval File (DRF) format |
-i string | the input file of data records that reference the CRF image
to be included. Data records are assumed to be in
data export format, unless |
-o string | the output file that will contain the resulting PDF document. If no output file argument is present, the resulting PDF document will be written to standard output. |
-f string | an alternative file location for the
study filemap. This file is read to determine plate labels for bookmarking. If
the argument is not present, the |
-v string | an alternative file location for the
study visit map. This file is read to determine visit labels for bookmarking.
If the argument is not present, the |
-g string | an alternative file location for the
study page map. This file is read to determine visit labels for bookmarking.
If the argument is not present, the |
-s string | allows the specification of sort order by an external file. The file is expected to be in query sort order format. Without this option, no sorting of the input file is performed and images appear in the PDF document in the order that records appear in the input file. With this option, consecutive records for the same ID are sorted to follow the rules stated by the sortmap file. Note that no sorting is performed across IDs, only within IDs, and only when the IDs appear consecutively in the input file. |
-t string | the title to appear at the top of the
bookmark list. If a title is supplied, in addition to setting the text of
the bookmark title object, the title is also set in the PDF document information.
If the title contains any characters that are meaningful to the
shell, including spaces, the title must be enclosed in double quotes.
If no title is supplied, the default title of
|
-j string | customize the page header label using a combination of fixed
text and references to key and meta information. The default header is
|
-k string | customize the page footer label using a combination of fixed text and references to key and meta information. The default footer is blank. |
-n | reverses the order of nesting of visits and plates. Without
this option, the preferred order is to nest plates within visits, unless the
visit cannot be found in the visit map, in which case the visit (sequence)
is nested within the plate. If |
-b string | allows the specification of fields to be blinded (blanked out)
in the output PDF file.
The plate:field,field,field;plate:field,field
where Field numbers that are not valid for the plate are skipped. Where multiple plates are required, plate specifications are separated by semi-colons.
To implement the blindlist, DFpdf must read the study setup file.
The study
setup file may be provided with
|
| the DFdiscover study number (required) |
Exit Status
DFpdf exits with one of the following statuses:
0 | The command was successful. |
1 | The command was successful, but the resulting PDF file contained 0 pages. |
2 | The user does not have the necessary permission to execute the command. |
2 | The input file cannot be read, the setup definition cannot be read, the database server could not be contacted, or communication with the database server failed. |
36 | The required command-line arguments were not present or were incorrectly specified. |
Examples
Example 3.61. Use DFpdf without the use of the DFexplore option
This example involves creating a DRF using from the menu in DFexplore, and then running DFpdf from the command line to generate a PDF file of the saved record set.
To start the process, DFexplore was used to retrieve a set of records
from the study database. The retrieved records were then saved to the DRF
dde.drf.
Example contents of dde.drf
are shown below.
#user1 16/02/22|Records ready for DDE #Id|Visit|Plate 1002|0|1 1006|0|1 2035|1|2 2035|1|3 2035|1|4 2035|21|5 2035|23|5 2035|24|5
Next, DFpdf was run from the command line to create a PDF document from the DRF having a custom header label for each record in the PDF document. In this example, DFpdf was invoked by the following command:
% DFpdf -d -t "Subjects" -i /opt/studies/val254/drf/dde.drf \
-j "Subject %DFID, Image %DFRASTER" -o /opt/studies/val254/drf/dde.pdf 254
To generate the same file with password protection, the following command was invoked using the password "4aY3gh98B":
% DFpdf -c 4aY3gh98B -d -t "Subjects" -i /opt/studies/val254/drf/dde.drf \
-j "Subject %DFID, Image %DFRASTER" -o /opt/studies/val254/drf/dde.pdf 254
It is also possible to pipe the output from DFexport.rpc directly into DFpdf as illustrated in the following example:
% DFexport.rpc 254 1 - | DFpdf -t "Screening Data" \
-j "Subject %DFID, Image %DFRASTER" -o /opt/studies/val254/work/Screening.pdf 254
[11] If the string contains characters that are meaningful to the shell, such as space, quote, percent, etc., then the entire string must be enclosed in double quotes. The string can always be enclosed in double quotes, to ensure that no characters are interpreted by the shell.