|
CEEFTDS,
analogous to the C function strftime(),
converts the internal time and date to character strings according
to the specifications passed to it by the TD_STRUCT. These specifications
work in conjunction with the format conversions set in the current
locale. The current locale's LC_TIME category affects the behavior
of this service, including the actual values for the format specifiers.
CEEFTDS is sensitive to the locales set by setlocale() or
CEESETL, not to the Language Environment settings
from COUNTRY or CEE3CTY.
Syntax
>>-CEEFTDS--(--omitted_parm--,--time_and_date--,--maxsize--,---->
>--format--,--stringout--,--fc--)------------------------------><
- omitted_parm
- This parameter is reserved for future expansion and must be omitted.
For information about how to code an omitted parm, see Invoking callable services.
- time_and_date (input)
- Points to the time structure that is to be converted. The structure
has the following format:
- td_sec
- A 4-byte integer that describes the number of seconds in the range
of 0 through 59.
- td_min
- A 4-byte integer that describes the number of minutes in the range
of 0 through 59.
- td_hour
- A 4-byte integer that describes the number of hours in the range
of 0 through 23.
- td_mday
- A 4-byte integer that describes the day of the month in the range
of 1 through 31.
- td_mon
- A 4-byte integer that describes the month of the year in the range
of 0 through 12.
- td_year
- A 4-byte integer that describes the year of an era.
- td_wday
- A 4-byte integer that describes the day of the week in the range
of 0 through 6.
- td_yday
- A 4-byte integer that describes the day of the year in the range
of 0 through 365.
- td_isdst
- A 4-byte integer that is a flag for daylight savings time.
- maxsize (input)
- A 4-byte integer that specifies the maximum length (including
the string terminator) of the string that can be placed in stringout.
- format (input)
- A halfword length-prefixed character string (VSTRING) of 256 bytes
that contains the conversion specifications. The format parameter
is a character string containing two types of objects: plain characters
that are placed in the output string and conversion specifications
that convert information from time_and_date into
readable form in the output string. Each conversion specification
is a sequence of this form:
%[-][width][.precision]type
- %
- A percent sign (%) introduces a conversion specification. This
character is required.
- width (optional)
- An optional decimal digit string that specifies a minimum field
width. A converted value that has fewer characters than the field
width is padded with spaces to the left. If the decimal digit string
is preceded by a minus sign, padding with spaces occurs to the right
of the converted value.
If no width is given, for numeric fields
the appropriate default width is used with the field padded on the
left with zeros, as required. For strings, the output field is made
exactly wide enough to contain the string.
- precision (optional)
- An optional value that specifies the maximum number of characters
to be printed for the conversion specification. The precision value
is a decimal digit string preceded by a period. If the value to be
output is longer than the precision, it is truncated on the right.
- type
- Specifies the type of conversion to be performed. The characters
and their meanings are:
- %a
- The abbreviated weekday name (for example, Sun) defined by the abday statement
in the current locale.
- %A
- The full weekday name (for example, Sunday) defined by the day statement
in the current locale.
- %b
- The abbreviated month name (for example, Jan) defined by the abmon statement
in the current locale.
- %B
- The full month name (for example, January) defined by the month statement
in the current locale.
- %c
- The date and time format defined by the d_t_fmt statement
in the current locale.
- %d
- The day of the month as a decimal number (01 to 31).
- %D
- The date in %m/%d/%y format (for example,
01/31/91).
- %e
- The day of the month as a decimal number (1 to 31). The %e field
descriptor uses a two-digit field. If the day of the month is not
a two-digit number, the leading digit is filled with a space character.
- %E
- The combined alternative era year and name, respectively, in %o
%N format in the current locale.
- %F
- The ISO 8601:2000 standard date format, equivalent to %Y-%m-%d.
- %g
- The last 2 digits of the week-based year as a decimal number [00,99].
- %G
- The week-based year as a 4-digit decimal number.
- %h
- The abbreviated month name (for example, Jan) defined by the abmon statement
in the current locale. This field descriptor is a synonym for the %b field
descriptor.
- %H
- The 24-hour clock hour as a decimal number (00 to 23).
- %I
- The 12-hour clock hour as a decimal number (01 to 12).
- %j
- The day of the year as a decimal number (001 to 366).
- %m
- The month of the year as a decimal number (01 to 12).
- %M
- The minutes of the hour as a decimal number (00 to 59).
- %n
- Specifies a new-line character.
- %N
- The alternative era name in the current locale.
- %o
- The alternative era year in the current locale.
- %p
- The AM or PM string defined by the am_pm statement
in the current locale.
- %r
- The 12-hour clock time with AM/PM notation as defined by the t_fmt_ampm statement (%I:%M:%S
[AM|PM]) in the current locale.
- %S
- The seconds of the minute as a decimal number (00 to 60).
- %t
- Specifies a tab character.
- %T
- Represents 24-hour clock time in the format %H:%M:%S (for
example, 16:55:15).
- %U
- The week of the year as a decimal number (00 to 53). Sunday, or
its equivalent as defined by the day statement,
is considered the first day of the week for calculating the value
of this field descriptor.
- %w
- The day of the week as a decimal number (0 to 6). Sunday, or its
equivalent as defined by the .day statement,
is considered as 0 for calculating the value of this field descriptor.
- %W
- The week of the year as a decimal number (00 to 53). Monday, or
its equivalent as defined by the day statement,
is considered the first day of the week for calculating the value
of this field descriptor.
- %x
- The date format defined by the d_fmt statement
in the current locale.
- %X
- The time format defined by the t_fmt statement
in the current locale.
- %y
- The year of the century (00 to 99).
- %Y
- The year as a decimal number (for example, 1989).
- %z
- The offset from UTC in ISO8601:2000 standard format ( +hhmm or -hhmm ).
For example, "-0430" means 4 hours 30 minutes behind UTC (west of
Greenwich).
- %Z
- The time-zone name, if one can be determined (for example, EST);
no characters are displayed if a time zone cannot be determined.
- %%
- Specifies a percent sign (%) character.
- stringout (output)
- A halfword length-prefixed character string (VSTRING) of 256 bytes
that contains the formatted time and date output of the CEEFTDS service.
- fc (output/optional)
- A 12-byte feedback code, optional in some languages,
that indicates the result of this service. If you choose to omit this
parameter, refer to Invoking callable services for the
appropriate syntax to indicate that the feedback code was omitted.
The
following symbolic conditions can result from this service:
Code |
Severity |
Message number |
Message text |
---|
CEE000 |
0 |
— |
The service completed successfully. |
CEE3T1 |
3 |
4001 |
General Failure: Service could not be completed. |
CEE3VM |
3 |
4086 |
Input Error: The number of characters to be formatted must
be greater than zero. |
Usage notes - PL/I MTF
consideration—CEEFTDS is not supported in PL/I MTF
applications.
- This callable service uses the C/C++ runtime
library. The C/C++ library
must be installed and accessible even when this service is called
from a non-C program.
Examples - An example of CEEFTDS called by COBOL:
CBL LIB,QUOTE
*Module/File Name: IGZTFTDS
*************************************************
* Example for callable service CEEFTDS *
* Function: Convert numeric time and date *
* values to a string using specified *
* format string and locale format *
* conversions. *
* Valid only for COBOL for MVS & VM Release 2 *
* or later. *
*************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINFTDS.
DATA DIVISION.
WORKING-STORAGE SECTION.
* Use TD-Struct for CEEFTDS calls
COPY CEEIGZTD.
*
PROCEDURE DIVISION.
* Subroutine needed for pointer addressing
CALL "COBFTDS" USING TD-Struct.
STOP RUN.
*
IDENTIFICATION DIVISION.
PROGRAM-ID. COBFTDS.
DATA DIVISION.
WORKING-STORAGE SECTION.
* Use Locale category constants
COPY CEEIGZLC.
*
01 Ptr-FTDS POINTER.
01 Output-FTDS.
02 O-Length PIC S9(4) BINARY.
02 O-String PIC X(72).
01 Format-FTDS.
02 F-Length PIC S9(4) BINARY.
02 F-String PIC X(64).
01 Max-Size PIC S9(9) BINARY.
01 FC.
02 Condition-Token-Value.
COPY CEEIGZCT.
03 Case-1-Condition-ID.
04 Severity PIC S9(4) BINARY.
04 Msg-No PIC S9(4) BINARY.
03 Case-2-Condition-ID
REDEFINES Case-1-Condition-ID.
04 Class-Code PIC S9(4) BINARY.
04 Cause-Code PIC S9(4) BINARY.
03 Case-Sev-Ctl PIC X.
03 Facility-ID PIC XXX.
02 I-S-Info PIC S9(9) BINARY.
LINKAGE SECTION.
* Use TD-Struct for calls to CEEFTDS
COPY CEEIGZTD. *
PROCEDURE DIVISION USING TD-Struct.
* Set up time and date values
MOVE 1 TO TM-Sec.
MOVE 2 TO TM-Min.
MOVE 3 TO TM-Hour.
MOVE 9 TO TM-Day.
MOVE 11 TO TM-Mon.
MOVE 94 TO TM-Year.
MOVE 5 TO TM-Wday.
MOVE 344 TO TM-Yday.
MOVE 1 TO TM-Is-DLST.
* Set up format string for CEEFTDS call
MOVE 72 TO Max-Size.
MOVE 36 TO F-Length.
MOVE "Today is %A, %b %d Time: %I:%M %p"
TO F-String (1:F-Length).
* Set up pointer to structure for CEEFTDS call
SET Ptr-FTDS TO ADDRESS OF TD-Struct.
* Call CEEFTDS to convert numeric values
CALL "CEEFTDS" USING OMITTED, Ptr-FTDS,
Max-Size, Format-FTDS,
Output-FTDS, FC.
* Check feedback code and display result
IF Severity = 0
DISPLAY "Format " F-String (1:F-Length)
DISPLAY "Result " O-String (1:O-Length)
ELSE
DISPLAY "Call to CEEFTDS failed. " Msg-No
END-IF.
EXIT PROGRAM.
END PROGRAM COBFTDS.
*
END PROGRAM MAINFTDS.
- An example of CEEFTDS called by PL/I:
*PROCESS MACRO;
/*Module/File Name: IBMFTDS */
/****************************************************/
/* Example for callable service CEEFTDS */
/* Function: Convert numeric time and date values */
/* to a string based on a format specification */
/* string parameter and locale format conversions */
/****************************************************/
PLIFTDS: PROC OPTIONS(MAIN);
%INCLUDE CEEIBMAW; /* ENTRY defs, macro defs */
%INCLUDE CEEIBMCT; /* FBCHECK macro, FB constants */
%INCLUDE CEEIBMLC; /* Locale category constants */
%INCLUDE CEEIBMTD; /* TD_STRUCT for CEEFTDS calls */
/* use explicit pointer to local TD_STRUCT structure*/
DCL TIME_AND_DATE POINTER INIT(ADDR(TD_STRUCT));
/* CEEFTDS service call arguments */
DCL MAXSIZE_FTDS BIN FIXED(31); /* OUTPUT_FTDS size */
DCL FORMAT_FTDS CHAR(64) VARYING; /* format string */
DCL OUTPUT_FTDS CHAR(72) VARYING; /* output string */DCL 01 FC,
/* Feedback token */
03 MsgSev REAL FIXED BINARY(15,0),
03 MsgNo REAL FIXED BINARY(15,0),
03 Flags,
05 Case BIT(2),
05 Severity BIT(3),
05 Control BIT(3),
03 FacID CHAR(3), /* Facility ID */
03 ISI /* Instance-Specific Information */
REAL FIXED BINARY(31,0);
/* specify numeric input fields for conversion */
TD_STRUCT.TM_SEC=1; /* seconds after min (0-61) */
TD_STRUCT.TM_MIN=2; /* minutes after hour (0-59)*/
TD_STRUCT.TM_HOUR=3; /* hours since midnight(0-23)*/
TD_STRUCT.TM_MDAY=9; /* day of the month (1-31) */
TD_STRUCT.TM_MON=11; /* months since Jan(0-11) */
TD_STRUCT.TM_YEAR=94; /* years since 1900 */
TD_STRUCT.TM_WDAY=5; /* days since Sunday (0-6) */
TD_STRUCT.TM_YDAY=344;/* days since Jan 1 (0-365) */
TD_STRUCT.TM_ISDST=1; /* Daylight Saving Time flag*/
/* specify format string for CEEFTDS call */
FORMAT_FTDS = 'Today is %A, %b %d Time: %I:%M %p';
MAXSIZE_FTDS = 72; /* specify output string size */
CALL CEEFTDS ( *, TIME_AND_DATE, MAXSIZE_FTDS,
FORMAT_FTDS, OUTPUT_FTDS, FC );
/* FBCHECK macro used (defined in CEEIBMCT) */
IF FBCHECK( FC, CEE000 ) THEN
DO; /* CEEFTDS call is successful */
PUT SKIP LIST('Format '||FORMAT_FTDS );
PUT SKIP LIST('Results in '||OUTPUT_FTDS );
END;
ELSE
DISPLAY ( 'Format '||FORMAT_FTDS||
' Results in '||FC.MsgNo );
END PLIFTDS;
|