new function for current timestamp

FWIW, here are a few average execution time figures over 10,000 repetitions for various incarnations of nanosecond-capable time functions. The tests were performed on an idle z15 CPU. Subroutine GSTSTCK is a 5-line assembler routine to return the STCK instruction output to the caller. Subroutine GETSTCKC is a Metal C subroutine with a very minimal prolog and epilog that uses the __stck() builtin function to return the data to the caller. The clock-gettime() subroutine is the XL C/C++ subroutine of that name, with the stub statically linked into the COBOL test program. The z15 is running z/OS V2.5 and the COBOL compiler level is V6.4.0, P231130.

The DIFF-DEC and AVRG values are all in nanoseconds. As you can see from the averages, using an external routine takes about twice as long as the static C clock_gettime() subroutine, the COBOL FORMATTED-CURRENT-DATE function takes over 30 times as long to execute as the C clock_gettime() function and over 16 times as long as using an external subroutine.

+0000010000 CALLS TO EXTERNAL STCK FUNCTION GETSTCK

STCK=0XDEB53026869416C0,RC=+0000,STCK-INT=16047785789229373120,STCK-DEC=16047785789.229373120

STCK=0XDEB53026869416C0,RC=+0000,STCK-INT=16047785789229373120,STCK-DEC=16047785789.230096576,DIFF-DEC=00000000000.000723456,AVRG=00000000000.000000072

+0000010000 CALLS TO EXTERNAL STCK FUNCTION GETSTCKC STCK=0XDEB5302686AD63C0,RC=+0000,STCK-INT=16047785789231031232,STCK-DEC=16047785789.231031232

STCK=0XDEB5302686AD63C0,RC=+0000,STCK-INT=16047785789231031232,STCK-DEC=16047785789.231755392,DIFF-DEC=00000000000.000724160,AVRG=00000000000.000000072

+0000010000 CALLS TO FORMATTED-CURRENT-DATE FUNCTION

20240226T010732.449165000 20240226T010732.460793000,DIFF=00000000000.011628000,AVRG=00000000000.000001163

+0000010000 CALLS TO CLOCK_GETTIME() FUNCTION

CLKGETTM seconds=1708927652,nano=0460801284,HEXTM=0X65DC2AA41B774504

CLKGETTM seconds=1708927652,nano=0461182813,HEXTM=0X65DC2AA41B7D175D,DIFF=00000000000.000381529,AVRG=00000000000.000000038

I guess this is better than the current state of things (i.e., nothing really useful), but again I question why such a complex function is accepted while the simplest solution of just returning the 8- or 16-byte value of the TOD clock instructions directly is so much more efficient and effective? Compatibility with DB2 timestamps is I guess a "Good Thing (tm)" for those who need it, but what about CPU-bound processes that need much higher efficiency and far fewer CPU cycles spent? Let the application designers and programmers decide when they "need" DB2 timestamp compatibility and provide a (probably CPU-expensive) conversion function for those cases where it is needed, while still satisfying the need for an efficient, simple TOD clock value directly from COBOL code?

Thanks a lot Basil. This Is excatly what I was asking.

We have decided to accept the Idea for making an intrinsic function in COBOL that mimics the output of the DB2 CURRENT TIMESTAMP special register.

The interface of the function in COBOL will look like:

FUNCTION CURRENT-TIMESTAMP(<fractional second precision 0 to 12>). The default precision is 6.

and it will return a character string that represents the current date/time provided by the system on which the function is evaluated in the following format (identical to DB2z CURRENT TIMESTAMP):

example: CURRENT-TIMESTAMP(12) returns ‘2023-02-03-05.09.01.123456789012’

example: CURRENT-TIMESTAMP(0) returns ‘2023-02-03-05.09.01’

Each call to CURRENT-TIMESTAMP will produce the exact time at the time of the call. Multiple back to back calls to CURRENT-TIMESTAMP will not produce identical time values.

My initial idea was to have a High level function (like DB2 current timestamp) but with performance similar to the STCKE macro. STCKE have great performance, but you need to use assembler. DB2 current timestamp Is High level, but introduce the overhead in calling DB2. Also most COBOL programs use timestamps in the DB2 format, so It Is important to have a function that give the same format (low impact in implementing it). Regards.

Hi Basil,

I cannot create an exact replica of a DB2 timestamp using the formatted-current-date function:

MOVE FUNCTION FORMATTED-CURRENT-DATE(
Severe: The specified date, time, or combined date and time format strin
g argument-1 "'YYYY-MM-DD-hh:mm:ss.ssssss'" is not a valid input for "AL
PHANUMERIC FUNCTION FORMATTED-CURRENT-DATE". The statement was discarde
d.
'YYYY-MM-DD-hh:mm:ss.ssssss') TO WS-TIMESTAMP

I can of course add a MOVE '-' TO WS-TIMESTAMP(11:1) after the sentence, but it would be nicer if the function could generate what I need.

Hi Rune,

We followed up with the DB2 for z/OS team on the CURRENT TIMESTAMP mechanics. CURRENT TIMESTAMP for Db2z is read only special register and can’t be SET. If you want a timestamp with a specified precision, the special register can be referenced as CURRENT TIMESTAMP(integer), where integer can range 0 - 12 and the user can control the precision of the result by specifying the precision. The default precision is 6. CURRENT TIMESTAMP for DB2z returns the time-of-day clock in TIMESTAMP data type when SQL statement is executed.

Example

SELECT CURRENT TIMESTAMP(8) WITH TIME ZONE

FROM SYSIBM.SYSDUMMY1;

DB2 on z/OS returns '2023-09-20-15.53.37.21624740' (the expression of CURRENT TIMESTAMP return Db2 TIMESTAMP(8) data type)

This kind of functionality already exists in COBOL through intrinsic function FORMATTED-CURRENT-DATE except for the additional precision of up to 12 digits after the seconds decimal point where COBOL only supports up to 6 digits of precision currently. We can add support for the extra 6 digits of precision so it has the same precision as the DB2z CURRENT TIMESTAMP function.

FORMATTED-CURRENT-DATE reference --> https://www.ibm.com/docs/en/cobol-zos/6.3?topic=functions-formatted-current-date

Please let me know your thoughts. Thanks.

Hi Basil

I am looking for an intrinsic function that mimics DB2 set current timestamp.
12 digits would be preferred, but 9 digits will get us some of the way.

Thank you

Hi Rune, in addition to my previous update, can you please provide a bit of clarification on what you mean by “timestamp” in COBOL.

Are you looking for a new intrinsic function that mimics STCKE and/or Enterprise DB2 SET CURRENT TIMESTAMP?

ie is it a formatted value like

2021-03-24 16:34:26.123456789012

or

2342521616574866666 // number of seconds with pico-seconds precision (12digits) since January 1, 1970, 00:00:00 GMT
?

Hi Rune, any thoughts on our previous update regarding the precision requirements of 9 digits (instead of 12)? Would that be sufficient? Thanks.

Hi Rune,

Thanks for the clarification on your precision requirement of 12 digits after the seconds. We are wondering if we can support it up to 9 digits. Would that be sufficient for your task?

Regarding the intrinsic function name, it is explicitly defined in the COBOL 2014 Language Standard spec and to comply to the standard would bring best portability.

Hi Basil
I am aware that this functionality exists.

I am requesting the possibility to have 12 digits after the seconds.

And that this is a function specifically for timestamps.

COBOL has a lot of functions, but it can be difficult for users to find them, in our case the user is looking for something to generate timestamps, not something to generate the current date.

That the formatted current date function is able to generate time information breakes with the single responsibility principle, and in my opinion anything with time information in that function should be moved away from it, and into a function that is better named for working with time and timestamps, maybe even two functions.

Regards, Rune

This functionality exists in Enterprise COBOL 6.4 as mentioned in the link below:

https://www.ibm.com/docs/en/cobol-zos/6.4?topic=functions-formatted-current-date

"...The accuracy of the portion of the returned value that corresponds to the time format is determined by the z/OS® operating environment, up to and including millionth (1/1000000) of a second..."

Example output:

2023-02-16T16:28:24.161304

Relevant code:

IDENTIFICATION DIVISION.

PROGRAM-ID. X1.

ENVIRONMENT DIVISION.

DATA DIVISION.

WORKING-STORAGE SECTION.

PROCEDURE DIVISION.

BEGIN.

DISPLAY FUNCTION FORMATTED-CURRENT-DATE(

'YYYY-MM-DDThh:mm:ss.ssssss')

* 123456

stop run.

END PROGRAM X1.

This RFE is being accepted and will be updated once put into plan.