Bundled with the worker node software is a new command line interface that can be used to query the CatDV database to generate customised reports, or to automatically update the server for use in external scripts of various kinds. Unlike the regular Worker Node, where automated actions are triggered from within the CatDV system (by a clip status change on the server or by means of a watch folder), the command line interface is ideally suited for system integrators who need to update clips as a result of an externally triggered event.
To use the command line tool you need to access it from a Terminal window or DOS command prompt. It’s not a double clickable application. Either copy the ‘catdv’ executable to a location on your path (eg. /usr/local/bin or C:WINDOWSSYSTEM32) or edit your PATH variable. Alternatively, you can specify the full path to the executable. Once you have done this, typing “catdv -help” will display a list of available commands.
The CatDV command line interface requires a valid Worker Node license on the machine to run, and automatically picks up configuration details such as the server IP address (as well as the license activation code) from the Worker configuration file on that machine. The following settings are read from the worker config file, so you need to use the Worker Node application to edit these parameters: license code, server IP address, CatDV user name and password used to log on to the server, number of user-defined fields, and date format.
The following commands are available:
catdv -help, catdv -helpfields, catdv -helpquery
Display a summary of available commands, a list of fields and their identifiers, and information about defining clip queries.
catdv -version, catdv -config
Display the version number of the application or a summary of the configuration information read from the CatDV Worker Node file.
Establish a connection to the server and display statistics about the database.
catdv -getProperty property
Return a server property. Valid property names include ‘version’, ‘startupError’, ‘warningMessage’, ‘isEnterprise’, ‘isRegistered’, ‘regLicense’, ‘regExpires’, ‘catdv.allowAnonymous’, ‘catdv.useRecycleBin’
catdv -groups, catdv -users
Display a list of all the production groups and users on the server, including their ids. (A format and output file can be specified if required, see below).
catdv [query] -catalogs (or -catalogsdetailed)
Display a brief or detailed list of catalogs on the server. If query is omitted, all the catalogs are listed (and the clip count is the total number of clips in each catalog), whereas if a query is specified only those catalogs that contain or more matching clips are shown, and the clip count is the number of clips that match the query. (A format and output file can be specified if required, see below).
catdv -distinct field
Display all the distinct values of a grouping field (such as Bin or Status) that occur in the database.
catdv [query] -summarise field
Similar to the -distinct command, this displays a list of all the distinct values of a field, together with a count of how many times that value occurs. If a query is specified, then only clips that match the query are considered. (A format and output file can be specified if required, see below).
catdv -thumbnail id
Extract a specific thumbnail image from the database given the thumbnail id (typically obtained from the poster id clip field). Binary JPEG data is returned and the results will normally be redirected to a file.
catdv query -count
Perform a clip query and display a count of how many clips match.
catdv query [options] -print [field,…]
Perform a clip query and display the matching clips. A list of which clip fields to display can be specified, otherwise a default list consisting of clip id, clip name, tape name, in and out timecode, format summary, and media file path is shown. (A format and output file can be specified if required, see below).
catdv query -print1 field
Perform a clip query and display a single field from all the matching clips. (Unlike the -print command, which returns full details of all the matching clips from the server and then selects which fields to display, this command is optimised to only return the requested data.)
catdv query -deleteclips
Perform a clip query and delete the matching clips, without asking for confirmation (though depending on how the server is configured, clips may be moved to the recycle bin rather than being deleted immediately).
catdv query -set field=value …
Perform a clip query and then update one or more fields of all the matching clips before publishing changes back to the server. Use -set field+=value to append the new value on the end of the existing value for the clip.
Fields and query terms
To specify a particular clip field you can use its short identifier (eg. “NM1”), its display name (eg. “Status”) or its internal numeric identifier, if known (eg. 17).
To specify a query, one or more query terms need to be specified. By default, multiple terms are combined with a logical AND operator (ie. only those clips which match all the query terms are processed). The following query terms are supported:
Only return clips whose clip name includes the specified text
Return clips where are any logging or media field includes the specified text. (Logging fields include name, notes, bin and user-defined fields, while media fields also include read-only media metadata fields such as Exif exposure information, ID3 album and artist tags, P2 camera metadata, and similar fields.)
Return clips where any logging field includes the specified text.
Only return clips from the specified production group (whose id was returned by the -groups command)
Return clips whose media path contains the specified text
Return a specific clip given its id
Return all clips in the database, if no other query terms are specified.
Only return clips in the specified catalog. Use -catalogid 0 to display the contents of the recycle bin.
Specify the catalog by name
Return clips where the specified field exactly matches a particular value.
Specifiy a completely general query term, consisting of a field, comparison operator and value to compare against, together with optional modifiers. The following modifiers are recognised: % (make the comparison case sensitive, normally case is ignored), ^ (negate the query term, so only clips which don’t satisfy the condition are returned), * (include this term in a list of terms combined with a logical OR operator, where at least one of the terms must be satisfied for a clip to be returned). Fields may be specified either by name or identifier, as elsewhere. The comparison operator is given by a number, such as 4 for ‘is blank’ or 35 for ‘timecode between two values’. Type “catdv -helpquery” for a full list of comparison operators.
A number of modifier options are available with many of the commands above:
Only return the given number of clips at most. (By default, a limit of 50000 clips is applied. Specify 0 to turn off the built-in limit.)
Include all the members inside a metaclip rather than just displaying one entry for the metaclip as a whole.
Specify the format and delimiter when printing results. Use ‘tab’ (the default) for tab-separated text, ‘csv’ for comma-separated format, ‘bar’ to separate fields with a vertical bar character (|), and ‘xml’ to use an XML format.
By default, all results are printed to the console, unless -out is used to redirect the output to a specified file (depending on how you invoke the command you can also use shell redirection with the ‘>’ operator of course).
When printing results, sort the clips based on the specified field(s). These need not necessarily be in the list of fields being displayed. Precede the field name with ‘-’ to reverse the sort order.
Look up the identifier for a specific production group, for use in subsequent queries
catdv -groupid 12401 -summarise Status
Display a summary of how many clips there are with each status in the given production group
catdv -query U1=Smith -query Status=Approved -format xml > /tmp/smith.xml
Generate a report of approved clips relating to a particular customer
catdv -mediafile DSC01245.JPG -print ID,NM1,MF,P1 -sort -ID1
Display all clips whose media file matches the given name and print a summary, including the poster id. Sort them so the most recently imported file comes first.
catdv -thumbnail 189039 -out ~/Desktop/thumb01245.jpg
Extract the specified poster image to a file.
catdv -query “*U1=Interview” -query “*Bin=Interview” -print
Display clips where either User1 or Bin is “Interview”. When typing certain punctuation characters (eg, *, $, ! etc.) be aware that they may have special meaning to the command interpreter shell and may need to be “escaped” by enclosing them in single or double quotes.
catdv -query ^STS:4: -count
Display a count of how many clips have a status which isn’t blank (operator 4 means ‘is blank’).
catdv -query 108:2:/Volumes/Media -summarise 108
Display a count of how many clips there are in each folder below /Volumes/Media (108 is the numeric attribute id for ‘media folder’, operator 2 means ‘starts with’)
catdv -query U2:4: -query STS:4: -query MD1:22:,86400 -set U2=Peter -set Status=Overdue
Take all clips whose status and assignee (user field 2) are blank and which are more than 24 hours old (MD1 is modified date, operator 22 means ‘older than’, and 86400 is the number of seconds in one day) and assign them to Peter, marked as being overdue.
catdv -query ID:65:11965,11968,11979,11988,… -set ARCHV=”Archived to tape B17”
Update the archive status of a specified list of clips (whose identifiers were determined previously) to indicate that they have been successfully archived to tape. (Operator 65 means ‘is one of’).