Features Added in FOCUS 7.6.7

Twelve-hour Time Formats for Date-Time Values

Time components of a date-time value are, by default, displayed using the 24-hour system. If you want to display times in the 12-hour system, you must include an AM/PM option in the format specification.

The following table shows the valid options for displaying time values in the 12-hour system. Assume the date is February 5, 1999 and the time is 02:05:25 a.m.

Option	Meaning	Example
A	12-hour time display followed by AM or PM in uppercase.	Prints the hour from 01 to 12, followed by AM or PM. For example: USAGE = HHISA prints 02:05:25AM For example: USAGE = HYYMDSA prints 1999/02/05 2:05:25AM
a	12-hour time display followed by am or pm in lowercase.	Prints the hour from 01 to 12, followed by am or pm. For example: USAGE = HHISa prints 02:05:25am For example: USAGE = HYYMDSa prints 1999/02/05 2:05:25am
B	12-hour time display, followed by a space, followed by AM or PM in uppercase.	Prints the hour from 01 to 12, followed by a space, then by AM or PM. For example: USAGE = HHISB prints 02:05:25 AM For example: USAGE = HYYMDSB prints 1999/02/05 2:05:25 AM
b	12-hour time display, followed by a space, followed by am or pm in lowercase.	Prints the hour from 01 to 12, followed by a space, then by am or pm. For example: USAGE = HHISb prints 02:05:25 am For example: USAGE = HYYMDSb prints 1999/02/05 2:05:25 am

When the format specifies a date component as well as a time component, the hour is displayed with zero supression (for example, 1999/02/05 2:05:25 am). When there is no date component, the hour displays without zero supression (for example, 02:05:25 am).

Precision for Date-Time Values

How to:

Specify Precision for Date-Time Values

In prior releases, the seconds component of a date-time value could be displayed with zero, three, or six decimal digits. It can now be be displayed with zero through nine decimal digits.

In order to control the precision of the seconds component in a date-time format, you can specify a digit from 1 to 9 in the format.

Top of page

Syntax: How to Specify Precision for Date-Time Values

Special format components exist for three decimal digits (milliseconds, s), six decimal digits (microseconds, m), and nine decimal digits (nanoseconds, n). To display:

A Time-only value, when the format includes more than one time display component:
- The components must appear in the order hour, minute, second, millisecond, microsecond, nanosecond.
- The first component must be either hour, minute, or second.
- No intermediate component can be skipped. If hour is specified, the next component must be minute; it cannot be second.
- To display a specific number of digits, include the format for seconds (S) followed by the number of digits to display. Alternatively, you can specify one or more of the following components: milliseconds (s), microseconds (m), nanoseconds (n).
Both a date component and a time component, the time component is represented by one character, which specifies the smallest unit of time to be displayed. This character can be either:
- A number from 1 to 9, which specifies the number of decimal digits to display for the seconds component.
- One of the supported time components. In this case, all higher order time components will also be included in the display.

Top of page

Example: Specifying Precision for Date-Time Values

Assume the date is February 5, 1999 and the time is 02:05:25.123456789 a.m. The following request uses the nanosecond component or a precision in display formats and function calls:

DEFINE FILE VIDPART1
 TRANSDT/HYYMDn      = DT(19990205 02:05:25.123456789);
 O_HSsmn/HSsmn       = TRANSDT; 
 O_HHIS2/HHIS2       = TRANSDT; 
 O_HYYMDn/HYYMDn     = TRANSDT; 
 O_HYYMD1/HYYMD1     = TRANSDT; 
 O_HADD/HYYMD9       = HADD(TRANSDT, 'NS', 2, 12, 'HYYMD9'); 
 O_HCNVRT/A26        = HCNVRT(TRANSDT, '(H23)', 23, 'A26'); 
 O_HDIFF/D12.2       = HDIFF(O_HADD, TRANSDT, 'NS', 'D12.2');
 TRANSDATE_DATE/YYMD = HDATE(TRANSDT, 'YYMD'); 
 O_HDTTM/HYYMDn      = HDTTM(TRANSDATE_DATE,12, 'HYYMDn');
 O_HEXTR/HHIS9       = HEXTR(TRANSDT, 'n',12, 'HHIS9');
 O_HGETC/HYYMDn      = HGETC(12, 'HYYMDn'); 
 O_HINPUT/HYYMDn     = HINPUT(14, O_HCNVRT,12, 'HYYMDn');
 O_HMASK/HYYMDn      = HMASK(O_HEXTR, 'HISsmn', TRANSDT, 12, 'HYYMDn');
 O_HMIDNT/HYYMDn     = HMIDNT(TRANSDT,12, 'HYYMDn');
 O_HNAME/A10         = HNAME(TRANSDT, 'NANOSECOND', 'A10');
 O_HPART/I10          = HPART(TRANSDT, 'NANOSECOND', 'I10');
 O_HSETPT/HYYMDn     = HSETPT(TRANSDT, 'NS', 28, 12,'HYYMDn'); 
 O_HTIME/P20.2C      = HTIME(12,TRANSDT, 'D16');
END 
TABLE FILE VIDPART1
PRINT TRANSDATE NOPRINT TRANSDT
OVER O_HSsmn
OVER O_HHIS2 
OVER O_HYYMDn 
OVER O_HYYMD1 
OVER O_HADD   
OVER O_HCNVRT 
OVER O_HDIFF  
OVER O_HDTTM  
OVER O_HEXTR  
OVER O_HGETC  
OVER O_HINPUT 
OVER O_HMASK  
OVER O_HMIDNT 
OVER O_HNAME  
OVER O_HPART  
OVER O_HSETPT 
OVER O_HTIME  
WHERE TRANSDATE EQ DT(1991/06/19 04:11)
END

The output is:

TRANSDT   1999/02/05 02:05:25.123456789
O_HSsmn   25.123456789 
O_HHIS2   02:05:25.12
O_HYYMDn  1999/02/05 02:05:25.123456789
O_HYYMD1  1999/02/05 02:05:25.1
O_HADD    1999/02/05 02:05:25.123456791
O_HCNVRT  19990205020525123456789
O_HDIFF                            2.00
O_HDTTM   1999/02/05 00:00:00.000000000
O_HEXTR   00:00:00.000000789
O_HGETC   2008/06/25 10:26:52.343644000
O_HINPUT  1999/02/05 02:05:25.000000000
O_HMASK   1999/02/05 00:00:00.000456789
O_HMIDNT  1999/02/05 00:00:00.000000000
O_HNAME   123456789
O_HPART                       123456789
O_HSETPT  1999/02/05 02:05:25.000000028
O_HTIME            7,525,123,456,789.00

Note:

Field O_HSsmn displays the seconds (S), milliseconds (s), microseconds (m), and nanoseconds (n) from TRANSDT.
Field O_HHIS2 displays the hours (H), minutes (I), and seconds (S) from TRANSDT. The seconds are displayed with two decimal digits (2).
Field O_HYYMDn displays TRANSDT with the date in YYMD format and the time down to nanoseconds (n).
Field O_HYYMD1 displays TRANSDT with the date in YYMD format and the time down to seconds with one decimal digit (1).
Field O_HADD is created by calling the HADD function to add 2 nanoseconds to the date-time value in TRANSDT.
Field O_HCNVRT is created by calling the HCNVRT function to convert the date-time value in TRANSDT to alphanumeric format.
Field O_HDIFF is created by calling the HDIFF function to subtract the date-time value in TRANSDT from the date-time version in O_HADD.
Field O_HDTTM is created by calling the HDTTM function to create a date-time field by taking the date from TRANSDATE_DATE and setting the time components to zero.
Field O_HEXTR is created by calling the HEXTR function to extract the nanoseconds (low order three digits of nine) from TRANSDT and set the remaining components to zero.
Field HGETC is created by calling the HGETC function to retrieve the current date and time and display them with 9 decimal digits for the seconds component. Note that not all operating systems return all 9 decimal digits, in which case the digits not returned display as zeros.
Field O_HINPUT is created by calling the HINPUT function to convert the alphanumeric date-time string stored in field O_HCNVRT to a date-time value and display it down to the nanosecond.
Field O_HMASK is created by calling the HMASK function to extract the hours, minutes, seconds, milliseconds, microseconds, and nanoseconds from O_HEXTR and take the remaining components from TRANSDT.
Field O_HMIDNT is created by calling the HMIDNT function to retrieve the date from TRANSDT and set the time to midnight.
Field O_HNAME is created by calling the HNAME function to retrieve the nanosecond component from TRANSDT in alphanumeric format.
Field O_HPART is created by calling the HPART function to retrieve the nanosecond component from TRANSDT in numeric format.
Field O_HSETPT is created by calling the HSETPT function to set the nanoseconds component to the value 28.
Field O_HTIME is created by calling the HTIME function to convert the time portion of TRANSDT to the number of nanoseconds.

Top of page

Reference: Usage Notes for Nanosecond Date-Time Format Component

This feature is not currently supported in Maintain.
ACTUAL formats for date-time fields can be up to H12. USAGE formats can be up to H23. FIXFORM supports /H12 for incoming binary date-time transaction values from a HOLD or SAVB file.
The following date-time functions take a component name as an argument: HADD, HDIFF, HNAME, HPART, and HSETPT. The component name for nanoseconds for use in these date-time functions is nanosecond, which can also be abbreviated as ns. In addition, the HEXTR and HMASK functions have a new component, n, that represents the low order three digits of nine decimal digits.
The following functions have arguments whose length depends on the precision of the date-time format:
- HADD, HDIFF, HINPUT, HMIDNT, HSETPT, and HTIME have a length argument. The length can be 8, 10, or 12, where 12 is needed if the seconds value has more than six decimal digits.
- HDTTM and HGETC have an argument for the length of the date-time value, which can be 8, 10, or 12, where 12 is needed if the seconds value has more than six decimal digits.
- HCNVRT takes one argument that specifies the format of the date-time field to be converted to alphanumeric and one for the length of that field. The length of these arguments can be up to 23. The format for the output must be long enough to hold all of the characters returned.
- HTIME converts the time portion of a date-time value to nanoseconds if the first argument is 12.

Using a Field as an EDIT Mask

How to:

Extract or Add Characters

You can store the mask used with the EDIT function in an alphanumeric string.

The EDIT function extracts characters from or adds characters to an alphanumeric string. It can extract a substring from different parts of the parent string, and can also insert characters from a parent string into another substring. For example, it can extract the first two characters and the last two characters of a string to form a single substring.

EDIT works by comparing the characters in a mask to the characters in a source field. When it encounters a nine in the mask, EDIT copies the corresponding character from the source field to the new field. When it encounters a dollar sign in the mask, EDIT ignores the corresponding character in the source field. When it encounters any other character in the mask, EDIT copies that character to the corresponding position in the new field. EDIT does not require an outfield argument because the result is alphanumeric and its size is determined from the mask value.

Top of page

Syntax: How to Extract or Add Characters

EDIT(fieldname, mask);

where:

fieldname

Alphanumeric

Is the source field.

mask

Alphanumeric

Is a character string enclosed in single quotation marks or a field containing the character string enclosed in single quotation marks. The length of the mask, excluding any characters other than nine and $, determines the length of the output field.

Top of page

Example: Extracting and Adding a Character to a Field Using a Field as the EDIT Mask

In the following example, EDIT extracts the first initial from the FIRST_NAME field and stores the result in FIRST_INIT. EDIT also adds dashes to the EMP_ID field and stores the result in EMPIDEDIT. The mask used to extract the first initial is stored in the virtual field named MASK1. The mask used to add dashes to the EMP_ID is stored in the virtual field named MASK2:

DEFINE FILE EMPLOYEE MASK1/A10 = '9$$$$$$$$$'; 
MASK2/A11 = '999-99-9999'; END
TABLE FILE EMPLOYEE
PRINT LAST_NAME AND COMPUTE
FIRST_INIT/A1 = EDIT(FIRST_NAME, MASK1);
EMPIDEDIT/A11 = EDIT(EMP_ID, MASK2);
WHERE DEPARTMENT EQ 'MIS';
END

The output is:

LAST_NAME        FIRST_INIT  EMPIDEDIT
---------        ----------  --------- 
SMITH            M           112-84-7612 
JONES            D           117-59-3129 
MCCOY            J           219-98-4371 
BLACKWOOD        R           326-17-9357 
GREENSPAN        M           543-72-9165 
CROSS            B           818-69-2173

Testing Whether a Value Exists in a File in Dialogue Manager

How to:

Test Whether a Value Exists in a File in Dialogue Manager

Reference:

Usage Notes for IN FILE

You can use the IN FILE phrase in Dialogue Manager to test whether a character value exists in a file and populate a Dialogue Manager (amper) variable with the result. The value of the variable is set to 1 if the test value exists in the file and 0 (zero) if it does not.

Top of page

Syntax: How to Test Whether a Value Exists in a File in Dialogue Manager

-SET &var3 = &var1 IN FILE filename1 [OR &var2 IN FILE filename2 ...];

where:

&var3: Is the variable that is populated with the value 1 if the result of the expression on the right side of the equal sign is true, or with the value 0 if the result is false.
&var1: Is the variable that contains the value to be searched for in filename1.
&var2: Is the variable that contains the value to be searched for in filename2.

Top of page

Example: Testing Whether a Variable Value Is in a File

The following FOCEXEC creates an alphanumeric HOLD file called COUNTRY1 with the names of countries from the CAR file. It then sets the variable &C equal to FRANCE. The IN FILE phrase returns the value 1 to &IN1 if FRANCE is in the HOLD file and 0 if it is not:

TABLE FILE CAR                                   
PRINT COUNTRY                                    
ON TABLE HOLD AS COUNTRY1 FORMAT ALPHA           
END                                              
-RUN                                             
-SET &C = 'FRANCE';                              
-SET &IN1 = &C IN FILE COUNTRY1;                
-TYPE THE VALUE IS &IN1

The output shows that FRANCE is in the file COUNTRY1:

THE VALUE IS 1

Top of page

Example: Using an IF Operator With IN FILE

The following FOCEXEC creates a SAVE file called COUNTRY1 with the names of countries from the CAR file. The first -SET command sets the variable &C equal to FRANCE. The IF operator in the second -SET command sets &IN1 to YES if the IN FILE phrase returns the value 1, or NO if it returns the value zero:

TABLE FILE CAR                                             
PRINT COUNTRY                                              
ON TABLE SAVE AS COUNTRY1                     
END                                                        
-RUN                                                       
-SET &C = 'FRANCE';                                        
-SET &IN1 = IF (&C IN FILE COUNTRY1) THEN 'YES' ELSE 'NO'; 
-TYPE THE ANSWER IS: &IN1

The output shows that the IN FILE phrase returns the value 1 and that the variable &IN1 is set to YES as a result:

THE ANSWER IS: YES

Top of page

Reference: Usage Notes for IN FILE

The result of the IN FILE phrase is an alphanumeric value (1 or 0) that can be used in a logical expression connected with AND and OR operators within same –SET command. This value cannot be used as an argument in an alphanumeric operation such as concatenation within the same -SET command.
In order for IN FILE to return the value 1, the values in the file and the search string must match exactly, starting with the leftmost byte in the file.
The file can be in any order and have duplicate values. The search stops when either the first match is found or the end of the file is reached. If the file is allocated but does not exist, the value 0 is returned. If the file is not allocated, the following message displays:
```
(FOC351) INPUT FILE NOT ALLOCATED:
```
The length of the variable used in the IN FILE phrase determines the number of bytes from the beginning of each record in the file used for comparison. Only an exact match on that number of bytes will return a 1. Trailing blanks in the variable will require the same number of trailing blanks in the file in order to match. For example, the following will match only the value 'ABC ' (ABC with three trailing blanks):
```
-SET &VAR1 = 'ABC   ';
-SET &VAR2 = &VAR1 IN FILE FILE1;
```

DEDIT Function

How to:

Extract or Add DBCS or SBCS Characters

If your configuration uses a DBCS code page, you can use the DEDIT function to extract characters form or add characters to a string.

DEDIT works by comparing the characters in a mask to the characters in a source field. When it encounters a nine (9) in the mask, DEDIT copies the corresponding character from the source field to the new field. When it encounters a dollar sign ($) in the mask, DEDIT ignores the corresponding character in the source field. When it encounters any other character in the mask, DEDIT copies that character to the corresponding position in the new field.

Top of page

Syntax: How to Extract or Add DBCS or SBCS Characters

DEDIT(inlength, source_string, mask_length, mask, outfield)

where:

inlength

Integer

Is the number of bytes in source_string. The string can have a mixture of DBCS and SBCS characters; therefore, the number of bytes represents the maximum number of characters possible in the source string.

source_string

Alphanumeric

Is the string to edit enclosed in single quotation marks, or the field containing the string.

mask_length

Integer

Is the number of characters in mask.

mask

Alphanumeric

Is the string of mask characters. Each nine (9) in the mask causes the corresponding character from the source field to be copied to the new field. Each dollar sign ($) in the mask causes the corresponding character in the source field to be ignored. Any other character in the mask is copied to the new field.

outfield

Alphanumeric

Is the field to which the result is returned, or the format of the output value enclosed in single quotation marks.

Top of page

Example: Adding and Extracting DBCS Characters

The following example copies alternate characters from the source string to the new field, starting with the first character in the source string, and then adds several new characters at the end of the extracted string:

The following example copies alternate characters from the source string to the new field, starting with the second character in the source string, and then adds several new characters at the end of the extracted string:

DSUBSTR Function

How to:

Extract a Substring

If your configuration uses a DBCS code page, you can use the DSUBSTR function to extract a substring based on its length and position in the parent string.

Top of page

Syntax: How to Extract a Substring

DSUBSTR(inlength, parent, start, end, sublength, outfield)

where:

inlength

Integer

Is the length of the parent string in bytes, or a field that contains the length. The string can have a mixture of DBCS and SBCS characters; therefore, the number of bytes represents the maximum number of characters possible in the parent string.

parent

Alphanumeric

Is the parent string enclosed in single quotation marks, or the field containing the parent string.

start

Integer

Is the starting position (in number of characters) of the substring in the parent string. If this argument is less than one or greater than end, the function returns spaces.

end

Integer

Is the ending position (in number of characters) of the substring. If this argument is less than start or greater than inlength, the function returns spaces.

sublength

Integer

Is the length of the substring in characters (normally end - start + 1). If sublength is longer than end - start +1, the substring is padded with trailing spaces. If it is shorter, the substring is truncated. This value should be the declared length of outfield. Only sublength characters will be processed.

outfield

Alphanumeric

Is the field to which the result is returned, or the format of the output value enclosed in single quotation marks.

Top of page

Example: Extracting a Substring

The following example extracts the 3-character substring in positions 4 through 6 from a 15-byte string of characters: