Chapter 3. Shell Level Programs
Prev		Next

Chapter 3. Shell Level Programs

Table of Contents

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

3.1. Introduction

The DFdiscover distribution includes several programs that can be executed on their own from a command line, or combined in shell scripts to build other programs (e.g. to export data sets for systems, or create study specific reports). All of the programs described in this section can be found in the DFdiscover executables directory, /opt/dfdiscover/bin with the exception of DFmkdrf.jnl and DFmkdrf.ec which are in /opt/dfdiscover/ecbin.

Permission to run these programs is controlled by UNIX file permissions that are set on DFdiscover installation to execute for user 'datafax' and users in group 'studies', but not for 'other' users.

The remainder of this chapter is a reference for each shell program.

3.2. User Credentials

DFdiscover includes many programs. Some operate only on a database server computer (referred to as server-side) while others operate on a user's desktop computer (referred to as client-side). The application of user login and permissions varies slightly in these two environments.

Interactive client-side programs like DFexplore, DFsetup, DFsend and DFadmin require the user to interactively provide a valid username and password each time they connect to a database server.

Conversely, the majority of the shell programs require a UNIX-like shell environment to function, and hence they may only be executed directly on a DFdiscover database server machine. Access to specific database information is granted based upon the DFdiscover permissions assigned to the user, where the user is identified by their UNIX login name.

Starting with release 2014.0.0, DFdiscover includes a third type of program. Programs of this type require a command line environment to execute and can be run from either the user's desktop computer (client-side) or from the database server computer (server-side). These programs are DFbatch, DFpdfpkg and DFexport. To authenticate, they require the same credentials that an interactive program does, specifically the username and password required to connect to a database server. Since there is no visual login dialog, these programs require a different interaction for authenticating, and there are two solutions for the user:

command-line options, the user can specify -S servername, -U username and -C password when the program is run, or
environment variables, the user can set the variables DFSERVER servername, DFUSER username and DFPASSWD password before the program is run.

Specification of command-line options takes priority if both command-line options and environment variables are supplied. It is not possible to mix solutions using a subset of command-line options and a complimentary set of environment variables. If any command-line option is specified, the expectation is that the command-line solution is preferred; otherwise, the environment variable solution is required.

3.2.1. Good Password Management

In many circumstances, it is poor practice to display or store a plain text password. Including a password in a shell script or in a cron job is not secure behavior, and is not recommended. Hence we strongly recommend that users do not use either the -C password command-line option or the DFPASSWD password environment variable. Instead, we encourage users to make use of the DFpass program to locally manage their DFdiscover passwords. After creating a matching entry with DFpass, a user does not need to subsequently specify a password with either -C password or DFPASSWD password.

The recommended practice then is to create/manage passwords locally using DFpass and subsequently use either the two command-line options, -S servername and -U username, or the two environment variables DFSERVER servername and DFUSER username.

Use of locally managed passwords is limited to the DFattach, DFbatch, DFpdfpkg, DFexport, DFreport and DFuserPerms programs.

3.2.2. Order of Evaluation

When determining the authentication credentials to use for one of DFbatch, DFpdfpkg or DFexport, the order of evaluation is as follows and only the first matching combination, if any, is used:

If all three command line options -S servername, -U username and -C password are specified, use them.
If all three environment variables DFSERVER servername, DFUSER username and DFPASSWD password are defined, use them.
If both of the command line options -S servername and -U username are specified, use them together with the matching password entry previously stored via DFpass.
If both of the environment variables DFSERVER servername and DFUSER username are defined, use them together with the matching password entry previously stored via DFpass.

3.3. Organization of Reference Pages

The description of each program in this reference is divided into sections.

Name. The official name of the program.

The program name is case sensitive and must be typed exactly as specified. This section also provides the brief purpose of the program.

Synopsis. Lists all of the valid options for the program invocation.

Each option is either optional or required. Most options are, not surprisingly, optional, a few are required, and yet others may require one option from a specific subset. Each option type is indicated with a particular notation. Except for some required options, a program option begins with - and is followed by an option letter. In some cases this may be enough to select the option; in other cases, the option letter will be further followed by an option string.

	Option Letter
	An option letter may be given different meanings in different programs. There is no requirement that the same option letter infers the same meaning when used across different programs.

Table 3.1. Notation for program options

Notation	Meaning
{study}	Required. The program will not function without the specification of this option. The option must be provided at the specified location in the list of options.
[-o]	Optional. The option may be omitted. The program will function, albeit differently, with or without this option.
[-o `string` ]	Optional, with an additional option string. The option may be omitted, however when it is used, the option letter must be immediately followed by a space and the option string. The option string generally ends at the next white-space character, however some option strings may contain spaces, and may or may not require that such strings be delimited by `"`.
{ [-s] \| [-u] }	One of the options from the specified subset is required.
[ [-s #] \| [-u #] ]	Several options are possible but only zero or one from the specified subset may be used.

Description. Describes the program purpose in greater detail.

This section describes exactly how the program works in terms of environment, input requirements, output format, dependencies, etc. It may also include detailed information about the program behavior for commonly used combinations of options.
Options. Detailed listing of available options, their use, and their meaning.
Examples. Illustrates the program options and output by way of example(s).
See Also. Lists other reference materials, typically other programs, that are relevant to the program. This in an optional section.
Limitations. Describes any limitations in the use or capabilities of the program. This in an optional section.

Prev		Next
Chapter 2. DFdiscover Study Files	Home	DFaccess.rpc