Date and Time formats in Content Manager OnDemand

Introduction

One of the most important field types in IBM Content Manager OnDemand is Date and Time formats. Timestamps appear in various locations in IBM CMOD -- Load IDs, the Segment Table, etc. There has been a slow evolution of date and time stamps, culminating with a switch to database-native formats for the databases that OnDemand supports. This article will explain the historical time formats, describe how to convert them in a variety of ways, and demonstrate how you can use IBM CMOD date formats for special reports.

History

In the early 1990's when IBM CMOD was developed, two facts necessitated the IBM Content Manager OnDemand developers to use their own date formats: The high cost of data storage, and the lack of built-in date/time formats in the database engines that were supported by OnDemand. The solution was to store dates as integers - representing the number of days since midnight, January 1st, 1970, UTC, and times as the number of seconds since the same date. If you're a UNIX or Linux user, you should recognize this date as the 'epoch' date, used as their internal representation for dates for most operating system functions. In fact, IBM CMOD used UNIX epoch as its internal date-and-time format up until IBM CMOD v9.5.

This relationship means you can fairly easily convert between UNIX epoch date/time format, and the IBM CMOD arsdate format - simply divide by 86400 -- the number of seconds in a day.

 129600 / 86400 = 1.5

A UNIX time format of 129600 is January 2nd, 1970 at 12:00pm UTC. Timezone calculations add complexity, but there are functions available in most programming languages to make this adjustment for you, based on your server's configured time zone.

Old IBM CMOD Date Formats

The old formats are simply stored as integers. Searching OnDemand through arsdoc query will perform the conversion to a human readable format, as per the IBM CMOD Folder Definition. But if you need to convert from an OnDemand date format into a human readable format, you can use the arsdate command.

IBM Content Manager OnDemand's arsdate utility will assist in converting date formats from the command line (see below for IBM CMOD's arsdate examples):

 # Convert from a CMOD internal date format to a human readable date:
 # arsdate -a 17034
 17034	->	08/20/16

 # Convert from a CMOD internal time format to a human readable date & time format:
 # arsdate -i 1489982862
 1489982862	->	03/20/17 04:07:42

 # Convert from a human readable date to the IBM CMOD internal date format:
 # arsdate -a 11/28/16
 11/28/16	->	17134

New Formats

The new date/time formats introduced in IBM CMOD v9.5 use the native date/time fields in your chosen database engine. This greatly simplifies date & time calculations and queries, as the database can use highly optimized search functions to complete user requests. Unfortunately, OnDemand Application Group data will need to be migrated to use these new date formats, which is best done at the time of an upgrade or data migration. Another improvement is that native database date formats support a MUCH wider range of dates. Prior to IBM CMOD v9.5, the range of dates that could be stored in CMOD were from 1970 until 2070 for date fields, and from 1970 to 2038 for date/time fields. Now, with OnDemand's date formats,

Converting Between Old and New

IBM CMOD arsdate command

  # arsdate
  ARS4500I Usage: arsdate [-a|-i|-z] [-A|-I|-Z] [-C] [-d] [-D] [-f] [-F] [-g] [-h] [-m] [-n] [-s] [-t] [-y] (value | number)
  Version:  10.1.0.2
    -a               Input date type (default)
    -A               Output date type (defaults to input type)
    -C               Convert to/from OD internal type and database type
    -d <days>        Days to add
    -D               Database type (default is OnDemand internal type)
    -f <input_fmt>   Input format string
    -F <output_fmt>  Output format string
    -g               Get today's date
    -h <hours>       Hours to add
    -i               Input date/time type (without timezone)
    -I               Output date/time type (without timezone)
    -m <months>      Months to add
    -n <mins>        Minutes to add
    -s <secs>        Seconds to add
    -t               time format
    -y <years>       Years to add
    -z               Input date/time type (with timezone)
    -Z               Output date/time type (with timezone)
    -1 <trace_file>  Trace file
    -2 <trace_level> Trace level