FORMAT Command

Description:

This command translates characters from one format into another. This makes it easier to manipulate character strings that have been output from the system under test, or which are to be input into that system.

In all translations, the command requires three elements:

The target variable that will receive the translated value. This may be either a character variable or an integer variable.

A format string defining the type of translation required. For an integer target variable, the format string must only contain a single format identifier; for a character variable, the format string may contain multiple identifiers and/or ordinary characters that are to be copied unchanged to the target variable.

One or more values to be translated; these may be specified as variables or as literal text. A single value must be specified for each of the format identifiers in the format string; the data type of each must agree with the associated format identifier and the data type of the target variable, as discussed below. Note that any discrepancies in this respect are detected at run-time and are not picked up by the compiler.

The following types of translation are supported:

%U - Translate each alphabetic character in the input string into its uppercase equivalent. Both source and target variables must be character variables. The source string if necessary is truncated to fit the target variable.

%L - Translate each alphabetic character in the input string into its lowercase equivalent. Both source and target variables must be character variables. The source string if necessary is truncated to fit the target variable.

%D - Convert a character string date value into numeric format (representing the number of days since the Smithsonian base date of 17-Nov-1858). The target variable must be an integer variable, and the source variable a character string containing a valid date; this can be either in the default style for the platform on which the script is running or in the fixed format "DD-MMM-CCYY" (where "CC" is optional).

This format identifier may also be used to convert a numeric date value (representing the number of days since the Smithsonian base date of 17-Nov-1858) into a character string in the fixed format "DD-MMM-CCYY". The source variable must be an integer variable and the target variable a character string, which will be truncated if necessary.

%T - Convert a character string time value into a numeric format (representing the number of 10 milli-second `ticks' since midnight). The target variable must be an integer variable, and the source variable a character string containing a valid time; this can be either in the default style for the platform on which the script is running or in the form "HH:MM:SS.MMM" (where ".MMM" is optional).

This format identifier may also be used to convert a numeric time value (representing the number of 10 milli-second ticks since midnight) into a character string in the fixed format "HH:MM:SS.MMM". The source variable must be an integer variable and the target variable a character string, which will be truncated as required.

Format:

 FORMAT (target-variable, format-string, {&}
 	 variable {,variable ...}) {&}
 	 {{,}ON ERROR GOTO err_label}

Parameters:

target-variable

The name of an integer or character variable into which the result of the operation is placed.

format-string

A quoted character string containing the string to be formatted and containing a number of format identifiers. The format identifiers must be compatible with the data types of the variables that follow.

variable

One or more integer or character variables or literals to be translated. The number of variables must correspond with the number of format identifiers in the format string. The data type of each variable must match the corresponding format identifier and the target variable.

err_label

A label defined within the current scope of the script, to which control branches if an error occurs.

Examples:

 FORMAT (date_string, &
 	 "The date is %D today, and the time is %T", &
 	 int-date, int-time), ON ERROR GOTO end
 FORMAT (date_value, "%D", char-date), ON ERROR GOTO frm_err
 FORMAT (uc_string, "Name in uppercase is %U", lc_string)

See also:

Output Stream Handling Commands