Programmer Guide

Release 5.4.0

All rights reserved. No part of this publication may be re-transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of DF/Net Research, Inc. Permission is granted for internal re-distribution of this publication by the license holder and their employees for internal use only, provided that the copyright notices and this permission notice appear in all copies.

The information in this document is furnished for informational use only and is subject to change without notice. DF/Net Research, Inc. assumes no responsibility or liability for any errors or inaccuracies in this document or for any omissions from it.

All products or services mentioned in this document are covered by the trademarks, service marks, or product names as designated by the companies who market those products.

Google Play and the Google Play logo are trademarks of Google LLC. Android is a trademark of Google LLC.

App Store is a trademark of Apple Inc.

May 19, 2021

Table of Contents

1. Getting Help
2. Conventions
1. Introduction
1.1. About This Guide
1.2. DFdiscover Programming Limits
2. DFdiscover Study Files
2.1. Introduction
2.2. DFdiscover study directories
2.3. Study File Permissions
2.4. Format used to describe files
2.5. DFdiscover Retrieval Files (DRF)
2.6. The study data directory
2.6.1. Temporary data files
2.6.2. Plate data files
2.6.3. Query data files
2.6.4. Reason for change data files
2.6.5. Newly arrived data file
2.6.6. Journal files
2.6.7. Index files
2.7. The study ecsrc directory
2.8. The study lib directory
2.9. The study lut directory
2.10. The study work directory
3. Shell Level Programs
3.1. Introduction
3.2. User Credentials
3.2.1. Good Password Management
3.2.2. Order of Evaluation
3.3. Organization of Reference Pages
3.4. Alphabetical Listing
DFaccess.rpc — Change access to a study database or , or query their current access status.
DFattach — Attach one or more external documents to keys in a DFdiscover study
DFaudittrace — Used by the DF_ATmods report to read study journal files. DF_ATmods produces an audit trail report showing database modifications for the specified study.
DFbatch — Process one or more batch edit check files
DFcompiler — Compile study-level edit check programs and output any warnings and/or errors encountered in the syntax.
DFdisable.rpc — Disable a study database server or incoming fax daemon to make them unavailable to clients and incoming faxes
DFenable.rpc — Enable a study database server or incoming fax daemon following a previous
DFencryptpdf — Protect a PDF file by encrypting it with the specified password
DFexport — Client-side, command-line interface for exporting data by plate, field or module; exporting change history; or exporting components of study definition
DFexport.rpc — Export data records from one or multiple plates from a study data file
DFfaxq — Display the members of the outgoing fax queue
DFfaxrm — Remove faxes from the outgoing fax queue
DFget — Get specified data fields from each record in an input file and write them to an output file
DFgetparam.rpc — Retrieve and evaluate the value of the requested configuration parameter
DFhostid — Display the unique DFdiscover host identifier of the system
DFimageio — Request a study CRF image from the database
DFimport.rpc — Import database records to a study database from an ASCII text file
DFlistplates.rpc — List all plate numbers used in the study
DFlogger — Re-route error messages from non-DFdiscover applications to syslog, which in turn writes the messages to the system log files, as configured in /etc/syslog.conf.
DFpass — Locally manage user credentials for client-side command-line programs.
DFpdf — Generate bookmarked PDF documents of CRF images
DFpdfpkg — Generate multiple bookmarked PDF files for specified subject IDs or sites
DFprint_filter — Format input file(s) for printing to a PostScript® capable printer, and print to a specified printer
DFprintdb — Print case report forms merged with data records from the study database
DFpsprint — Convert one or more input CRF images into PostScript®
DFqcps — Convert a Query Report, previously generated by DF_QCreports, into a PDF file with barcoding, prior to sending the report to a study site
DFreport — Client-side, command-line interface for executing reports
DFsas — Prepare data set(s) and job file for processing by SAS®.
DFsendfax — Fax or email a plain text, PDF, or TIFF file to one or more recipients
DFsqlload — Create table definitions and import all data into a relational database
DFstatus — Display database status information in plain text format
DFtextps — Convert one or more input files into PDF
DFuserdb — Perform maintenance operations on the user database
DFversion — Display version information for all DFdiscover executables (programs), reports, and utilities
DFwhich — Display version information for one or more DFdiscover programs, reports and/or utilities
4. Utility Programs
4.1. Introduction
4.2. Alphabetical Listing
DFaddHylaClient — Create the symbolic links necessary for accessing HylaFAX on a DFdiscover server
DFcertReq — Request an SSL certificate signing for DFedcservice.
DFclearIncoming — Clean out the fax receiving directory, processing all newly arrived faxes
DFcmpSchema — Apply the data dictionary rules against the study database
DFcmpSeq — Determine the appropriate values for each .seqYYWW file
DFisRunning — Determine if the DFdiscover master program is currently running on the licensed DFdiscover machine
DFmigrate — Upgrade study setup and configuration files from an old DFdiscover version to the current version.
DFras2png — Convert Sun raster files in the study pages directory into PNG files
DFshowIdx — Show the per plate index file(s) for a specific study
DFstudyDiag — Report (diagnose) the current status of a study database server
DFstudyPerms — Report, and correct, the permissions on all required DFdiscover sub-directories and files for a study
DFtiff2ras — Convert a TIFF file into individual PNG files
DFuserPerms — Import and update users and passwords, and optionally import roles, role permissions, and user roles
5. Edit checks
5.1. Introduction
5.1.1. DFopen_study and DFopen_patient_binder
5.2. Language Features
5.3. Database Permissions
5.4. Language Structure
5.4.1. return and exit statements
5.5. Variables
5.5.1. Variables and Types
5.5.2. Database Variables
5.5.3. Positional Variables
5.5.4. Local Variables
5.5.5. Global Variables
5.5.6. Variable Groups
5.5.7. Date Variables
5.6. Missing/Blank Data
5.6.1. dfblank
5.6.2. dfmissing
5.6.3. dfmissval
5.6.4. dfmisscode
5.6.5. dfmissingrecord
5.6.6. dflostcode
5.6.7. dflosttext
5.6.8. Missing Records
5.6.9. Examples
5.7. Arithmetic Operators
5.7.1. Addition
5.7.2. Subtraction
5.7.3. Multiplication/Division/Modulus
5.7.4. Exponentiation
5.7.5. Assignment
5.8. Conditional Execution
5.8.1. Comparison Operators
5.8.2. Logical Operators
5.8.3. if/else
5.9. Built-in Functions and Statements
5.9.1. Edit check Function Compatibility Notes
5.9.2. dfaccess
5.9.3. dfaccessinfo
5.9.4. dfalias2id
5.9.5. dfask
5.9.6. dfbatch
5.9.7. dfcapture
5.9.8. dfcenter
5.9.9. dfclosestudy
5.9.10. dfdate2str
5.9.11. dfday
5.9.12. dfdirection
5.9.13. dfentrypoint
5.9.14. dfexecute
5.9.15. dfgetfield
5.9.16. dfgetlevel/dflevel
5.9.17. dfgetseq
5.9.18. dfhelp
5.9.19. dfid2alias
5.9.20. dfillegal
5.9.21. dfimageinfo
5.9.22. dflegal
5.9.23. dflength
5.9.24. dflogout
5.9.25. dfmail
5.9.26. dfmatch
5.9.27. dfmessage/dfdisplay/dferror/dfwarning
5.9.28. dfmetastatus
5.9.29. dfmode
5.9.30. dfmoduleinfo
5.9.31. dfmonth
5.9.32. dfmoveto
5.9.33. dfneed
5.9.34. dfpageinfo
5.9.35. dfpassword
5.9.36. dfpasswdx
5.9.37. dfplateinfo
5.9.38. dfpref
5.9.39. dfprefinfo
5.9.40. dfprotocol
5.9.41. dfrole
5.9.42. dfsiteinfo
5.9.43. sqrt
5.9.44. dfstay
5.9.45. dfstr2date
5.9.46. dfstudyinfo
5.9.47. dfsubstr
5.9.48. dftask
5.9.49. dftime
5.9.50. dftoday
5.9.51. dftool
5.9.52. dftrigger
5.9.53. dfvarinfo
5.9.54. dfvarname
5.9.55. dfview
5.9.56. dfvisitinfo
5.9.57. dfwhoami
5.9.58. dfyear
5.9.59. int
5.10. Query operations
5.10.1. dfaddqc
5.10.2. dfaddmpqc
5.10.3. dfanyqc
5.10.4. dfanyqc2
5.10.5. dfanympqc
5.10.6. dfdelmpqc
5.10.7. dfeditqc
5.10.8. dfreplyqc
5.10.9. dfresqc/dfunresqc
5.10.10. dfqcinfo
5.10.11. dfqcinfo2
5.11. Reason operations
5.11.1. dfaddreason
5.11.2. dfanyreason
5.11.3. dfautoreason
5.11.4. dfreasoninfo
5.12. Lookup Tables
5.12.1. Pre-requisites
5.12.2. dflookup
5.13. Looping
5.13.1. while
5.13.2. break
5.13.3. continue
5.14. User-Defined Functions
5.14.1. Sharing edit check files with the #include directive
5.15. Examples and Advice
5.16. Optimizing Edit checks
5.16.1. Saving Time for the User
5.16.2. Limitations in the Language
5.16.3. Maximize Cache
5.16.4. Simplify Conditional Testing
5.16.5. Reduce the Number of Function Calls
5.16.6. Shortcut, and Order of, Evaluation
5.16.7. Delay Message Construction
5.17. Creating generic edit checks
5.17.1. More Examples
5.18. Debugging and Testing
5.18.1. Debugging
5.18.2. Testing
5.18.3. Compiling and Reloading Edit checks
5.19. Language Reference
5.19.1. Identifiers (edit check and variable names)
5.19.2. String Constants
5.19.3. Maximum number of instructions per edit check execution
5.19.4. Reserved Words
6. Batch Edit checks
6.1. Introduction
6.1.1. Overview
6.1.2. About this chapter
6.2. DFbatch Basics
6.2.1. The DFbatch Layer
6.2.2. Do you need DFbatch?
6.2.3. How does DFbatch work?
6.2.4. Getting Started
6.2.5. Summary
6.3. Using DFbatch
6.3.1. General Control File Layout
6.3.2. Invoking DFbatch
6.3.3. Strategies for using DFbatch
6.4. Limitations
6.4.1. Default actions for interactive functions
6.4.2. Not possible with DFbatch
6.4.3. Not recommended with DFbatch
6.5. Example Control Files
6.6. Common Pitfalls and System Messages
6.6.1. Common Pitfalls
6.6.2. System Messages
6.7. BATCHLIST Element Reference
6.7.1. BATCHLIST Document Type Definition
6.7.2. Organization of Reference Pages
6.7.3. Reference Pages
6.8. BATCHLOG Element Reference
6.8.1. BATCHLOG Document Type Definition
6.8.2. Element Reference
6.9. XML Language Basics
6.9.1. The Rules of XML
6.9.2. Companions to XML
6.9.3. Recommended Reading
7. Writing Your Own Reports
7.1. General Guidelines
7.2. Installing Your Reports
7.3. Input Data Files
7.4. Programming Tools
7.5. An Example
7.6. Writing Documentation for Study Specific Reports
8. DFsas: DFdiscover to SAS®
8.1. An Example
8.1.1. Global Specifications
8.1.2. Data Retrieval Specifications
8.1.3. SAS® Procedures
8.1.4. Running DFsas
8.2. Creating a DFsas job file
8.2.1. Impact of SAS® limits
8.2.2. Creating an initial DFsas job file
8.2.3. String splitting
8.2.4. String truncation
8.2.5. Date exporting
8.2.6. A sampling of other options
8.3. Creating SAS® job and data files
8.3.1. Force Option
8.3.2. Export Script Option
8.3.3. Use Field Alias Option
8.3.4. Syntax Checks
8.4. Date Fields
8.4.1. Global Statements
8.4.2. Qualified Dates
8.4.3. Time Qualifiers
8.4.4. Default Actions Performed When Creating a DFsas Job File
8.5. String Fields
8.5.1. String Splitting
8.5.2. Extracting Sub-Strings
8.5.3. Retaining Quotes in String Fields
8.6. DFsas Job File Syntax
8.6.1. Global Specifications
8.6.2. Data Retrieval Specifications
8.6.3. SAS® Procedures
8.7. Creating a Normalized Data Set
8.7.1. Merge
8.7.2. Specifying Data Fields
8.7.3. String Fields in Normalized Data Sets
8.7.4. Case Selection
8.7.5. Value codes or labels
8.7.6. Variable Description
8.7.7. Specifying Normalized Records
8.7.8. Sorting a Normalized Data Set
8.7.9. Example Data File
9. DFsqlload: DFdiscover to Relational Database Tables
9.1. Introduction
9.1.1. Overview
9.1.2. About DFsqlload
9.2. DFsqlload and Relational Database Concepts
9.2.1. Why Relational Databases?
9.2.2. Why is DFsqlload a one-way street?
9.2.3. Relational Database Concepts
9.3. Using DFsqlload
9.3.1. DFsqlload defaults - a quick tutorial
9.3.2. DFsqlload in Detail
A. Copyrights - Acknowledgments
A.1. External Software Copyrights
A.1.1. DCMTK software package
A.1.2. Jansson License
A.1.3. Mimencode
A.1.4. RSA Data Security, Inc., MD5 message-digest algorithm
A.1.5. mpack/munpack
A.1.6. TIFF
A.1.7. PostgreSQL
A.1.8. OpenSSL License
A.1.9. Original SSLeay License
A.1.10. gawk
A.1.11. Ghostscript
A.1.12. MariaDB and FreeTDS
A.1.13. QtAV
A.1.14. FFmpeg
A.1.15. c3.js
A.1.16. d3.js