HLI: Field formatting options for HLI calls
Overview
This topic describes in detail the field formatting options for specifying data that is passed between Model 204 and an HLI application that uses an IFSTRT thread.
Use the information in this topic to code the edit specification parameter in an IFFTCH, IFGET, IFGETX, IFGETV, IFMORE, IFMOREX, IFUPDT, IFSTOR, or IFPUT call.
The following calls retrieve data:
- IFFTCH
- IFGET
- IFGETX
- IFGETV
- IFMORE
- IFMOREX
The following calls perform updating functions against the database:
- IFUPDT
- iFSTOR
- IFPUT
Note: IFFTCH, IFUPDT, and IFSTOR are used on a multiple cursor IFSTRT thread; IFGET, IFGETX, IFGETV, IFMORE, IFMOREX, and IFPUT are used on a single cursor IFSTRT thread.
Using a LIST specification for a retrieval call
An edit specification parameter specifies a LIST format option for an IFFTCH, IFGET, IFGETX, IFMORE, or IFMOREX (retrieval) call using the following syntax:
LIST (field name list);
An edit specification parameter specifies a LIST format option for an IFFTCH call against a value set cursor or an IFGETV call using the following syntax:
LIST;
The retrieval call returns the value of the fields named in the field name list in the following format:
'field value1' 'field value2' ... 'field value N';
where:
- Single quotation marks enclose each value and blanks separate the values.
- Single quotation marks in the data itself are converted to two quotes.
- Fields that are not contained in the record are returned as two single quotes (' '), which is the null value.
- You may use a %variable in the field name list in the LIST specification. The value for the %variable is specified in the %VARBUF and %VARSPEC parameters.
Using a DATA specification for a retrieval call
An edit specification parameter specifies a DATA format option for an IFFTCH, IFGET, IFGETX, IFMORE, or IFMOREX call using either of the following syntax forms:
DATA (field name list); DATA;
The retrieval call returns the value of the fields named in the field name list in the following format:
fn1='value1' fn2='value2'... fnN='valueN';
where fields that are not contained in the record appear as fn=.
Note: The DATA format option without a field name list retrieves all fields in the record and formats data in the same manner.
Using an EDIT specification for a retrieval call
An edit specification parameter specifies an EDIT format option for an IFFTCH, IFGET, IFGETX, IFMORE, or IFMOREX call using either of the following syntax forms:
EDIT (field name list) (edit formats); EDIT (field name list1) (edit format1) (field name list2)(edit format2);
An edit specification parameter specifies an EDIT format option for an IFFTCH call against a value set cursor or an IFGETV call using the following syntax:
EDIT (edit format);
The retrieval call returns the value of the field(s) named in the field name list in the format that is specified. See Examples of numeric edit format conversion for a listing of edit codes that can be used in an EDIT specification for IFFTCH, IFGET, IFGETV, IFGETX, IFMORE, or IFMOREX.
Guidelines for specifying an EDIT format
When specifying an EDIT format, the following guidelines apply:
- You can insert blanks before and/or after the field name list and edit format entries in the EDIT specification.
- Separate individual entries inside the edit format list with a comma.
- Repetition factors and parentheses are allowed. Blanks following a repetition factor or surrounding commas and parentheses are optional.
The following examples illustrate repetition factors:
2A(10),J(2)
is equivalent to:
A(10),A(10),J(2)
And
2(A(10),J(2))
is equivalent to:
A(10),J(2),A(10),J(2)
- For each name in the field name list, one edit format is selected. Repetition factors are expanded before the selection occurs. COL, POS, and X are not selected by field names, but are executed as they are encountered in the list of edit formats.
-
You can use a %variable in the field name list in the EDIT specification. The value for the %variable is specified in the %VARBUF and %VARSPEC parameters.
If the edit formats are exhausted before the field name list, selection wraps around to the beginning of the list of formats. Model 204 ignores extra items.
Using the V format
When the V format is specified, the edit format specified immediately after the V determines the format of the data values.
For example, if the EDIT specification contains VA(4), the following hexadecimal data would be stored in the data buffer to represent the three values, ABCD, 1234, and XYZ:
00000003C1C2C3C4F1F2F3F4E7E8E940
Note that the following edit formats cannot be specified after the V:
- M and V, which describe a collection of values.
- COL, POS, and X, which alter the data buffer pointers without manipulating a value.
- A left parenthesis (( ), which indicates a group of formats to be repeated.
V processes field occurrences in the same manner as the M function. The field name corresponding to the V format in the field name list is specified as field name(n), the first n-1 occurrences of the field are omitted.
Note that the VL format is equivalent to the M format, except that the data values are preceded by a 4-byte count rather than by a 1-byte count.
Handling fields that do not occur in the record
Model 204 handles fields that do not occur in the record in the following ways:
- If the first or nth occurrence of a field is specified and the field is not present in the record or fewer than n occurrences exists, then the appropriate pad characters are supplied for A(n), J(n), L(n), and U(n) formats, or zero length is indicated for L and M formats.
No characters are returned for A and J formats. A numeric zero is returned in the appropriate format for the B, P, E, Z, and F formats.
- If all occurrences are specified and there are no occurrences of the field in the record, no edit formats are used for that field. Place requests for fieldname(*) at the end of a list or in a separate IFFTCH, IFMORE, or IFMOREX call.
- Fields with the INVISIBLE attribute are treated as if the field does not occur in the record.
Examples of numeric edit format conversion
The following table shows examples of how Model 204 converts data for a numeric edit format specification.
| Edit format specification |
Model 204 data (character) |
User data (hexadecimal) |
|---|---|---|
| Z(5,2) | 18.21 | F0 F1 F8 F2 C1 |
| Z(5,2) | -18.21 | F0 F1 F8 F2 D1 |
| P(5,2) | 18.21 | 01 82 1C |
| P(3) | -372 | 37 2D |
| B(31,0) | 4095 | 00000FFF |
| B(15,2) | 10.25 | 0029 (binary 001010.01) |
| F(4) | 2 | 41200000 |
Using EDIT format codes for a retrieval call
The following table describes the edit format codes that may be specified in the (edit format) with the EDIT option in an IFFTCH, IFGET, IFGETV, IFGETX, IFMORE, or IFMOREX (retrieval) call.
| Code | Description |
|---|---|
| A | Place an n-character field value into n characters. |
| A(n) |
Left-justify a field value in an n-character area. This format pads with blanks if the field value is less than n or truncates if the field value is greater than n (the maximum of n is 255). |
| B(precision,scale) | The value is returned in two's complement binary form. precision specifies the number of bits in the numeric value, exclusive of the sign bit. Only two precision types are supported: 15 (halfword) and 31 (fullword). If both precision and scale are omitted, precision defaults to 15.
scale specifies the number of digits to the right of an implied binary point. The scale must not exceed the precision. If scale is omitted, it defaults to 0, indicating an integer value. A maximum of 12 significant bits of a fraction are returned. If scale is more than 12, the low-order bits are 0. |
| COL(n) or COLUMN(n) | Adds blanks to character position n in the data area. Specifying a column that has already been passed over is an error. |
| E(total length,significant digits,fractional digits) | |
| Convert numeric format (FLOAT, BINARY, CODED, NON-CODED) numbers to exponential format. The total length includes the number of significant digits as well as space for E and the exponent, and space for both any decimal point and for any positive and/or negative signs.
An insufficient total length results in a truncated representation of the given number. The number of significant digits is the total of whole number digits plus fractional digits. The maximum number of significant digits used in conversions and mathematical operations by Model 204 is 15 (extra digits are rounded to 15). |
|
| F(n) | The value is returned as a floating-point number.
Decimal floating-point fractions are represented internally as imperfect, base 16, floating-point numbers. To provide exact equality when two floating-point values are compared, the numbers are rounded. Also, when a floating-point value is too large or too small for its field or %variable, the value is truncated or expanded so that it correctly fits. Rounding, truncation, or expansion occurs in the following cases:
|
| J | Same as A. |
| J(n) | Right-justify a field value in an n-character area. Pads with blanks if the field value is less than n, or truncates if the field value is greater than n (the maximum value of n is 255). |
| L | The first byte is set to the number of data bytes that follow it. For example, 'ABC' would appear as the four-byte string X'03C1C2C3'. |
| L(n) | Same as J(n) except pads with binary zeros instead of blanks. |
| M | Collect all the occurrences of a field into a single data area. This area begins with a byte containing the number of occurrences. Each occurrence follows in L format. Specifying fieldname(n) in the field name list causes the first n-1 occurrences of the field to be omitted. |
| M(n) | Like M but each occurrence is in L(n) format. |
| P(precision,scale) | The value is returned in packed-decimal form. precision specifies the number of digits (not bytes) in the numeric value, exclusive of the sign. The maximum precision for a packed-decimal field is 15. If an even precision is specified, one extra high-order 0 digit is returned. If both precision and scale are omitted, the precision defaults to 5.
scale specifies the number of digits to the right of an implied decimal point. The scale must not exceed the precision. If scale is omitted, it defaults to 0, indicating an integer value. No error is indicated if the fractional portion of a value is truncated. |
| POS(n) | Skip to character position n in the data area, bypassing the original contents from the application program. Specifying a column which has already been passed over is an error. |
| U | Same as A. The U function can be used with unformatted data such as bit strings or floating-point numbers. |
| U(n) | Left-justify a field value in an n-character area; pads with binary zeros or truncate on the right as appropriate (n<255). |
| V | Collect all occurrences of a field into a single data area. The area begins with a four-byte count of the number of data values in the area. The format of the values is determined by the second edit format, which must be specified immediately after the V. See Using the V format for an example and a summary of restrictions. |
| X(n) | Add n blanks in the data area. |
| Z(precision, scale) | The value is returned in zoned-decimal form. The meaning of precision and scale is identical to that of the P format above except no padding is required for an even precision. |
Using a LIST specification for an updating call
An edit specification parameter specifies a LIST format option for an IFUPDT, IFSTOR, or IFPUT call using the following syntax:
LIST (field name list);
The fields and values in the field name list must be specified in the following format:
'field value1' 'field value2' ... 'field value N';
where:
- Field values in the data area correspond to the names in the field name list.
- Enclose the values in single quotation marks and separate them with blanks.
- Two consecutive quotation marks in a field value causes a single quotation mark to be retained in the stored data.
- Leading and trailing blanks within the enclosing quotation marks are retained.
- A field value specified as " (the null value) causes an existing field to be deleted or, if the field does not exist in the record, no action is taken.
- You can use a %variable in the field name list in the LIST specification. The value for the %variable is specified in the %VARBUF and %VARSPEC parameters.
Using a DATA specification for an updating call
An edit specification parameter specifies a DATA format option for an IFUPDT, IFPUT, or IFSTOR call using the following syntax:
DATA;
The value of the fields named in the field name list must be specified in the following format:
fieldname1='fieldvalue1' fieldname2='fieldvalue2' ... fieldnameN='fieldvalueN';
where the following rules apply:
- Follow each field name with an equal sign (=) and enclose each new field value in single quotation marks.
- Separate field name=value pairs with blanks.
- Two consecutive single quotation marks in a field value are stored as a single quotation mark in the record.
- The null value, fieldname=", causes the specified field to be deleted from the record. Or, if the field did not previously exist in the record, no action is taken.
- The DATA specification refers to the first occurrence of each field specified.
Using an EDIT specification for an updating call
An edit specification parameter specifies an EDIT format option for an IFUPDT, IFSTOR, or IFPUT call using the following syntax:
EDIT (field name list) (edit formats);
The format of the fields named in the field name list must be specified in the edit format. See EDIT format codes used with an updating call for a list of the edit codes that are used in an EDIT specification for IFUPDT, IFSTOR, or IFPUT.
Guidelines for specifying an EDIT format
When specifying an EDIT format for an IFUPDT, IFPUT, or IFSTOR updating call, the following guidelines apply:
- The value in the data area used with the EDIT specification does not require a final semicolon.
- Each name in the field name list corresponds in sequence to an edit format. Extra edit formats are ignored.
- If the list of edit formats is too short, Model 204 wraps around to the beginning of the list.
- You can use a %variable in the field name list in the EDIT specification. The value for the %variable is specified in the %VARBUF and %VARSPEC parameters.
Specifying significant digits using A, E, J, L, M, and U formats
For numbers passed as parameters in A, E, J, L, M, or U specifications, Model 204 ignores significant digits past 15 and treats them as zeros, regardless of precision.
Specifying a length for the E format
When you specify the E format for an updating function call, Model 204 ignores the significant digits and fractional digits parameters, but the total length specified must be accurate.
If the updating function call receives a total length that does not convert to a floating-point number, Model 204 displays an error message indicating that data is inconsistent. The number is not stored and the HLI call that produced the message receives a return code of 4.
Using the G format
The G (Generic) format allows you to perform complex updates to specific field values when an HLI program is executed. Through the use of a descriptor byte, you can use the G format to:
- Change the value of a field=value pair in a record
- Delete a specific value of the field in a record
- Bypass a specific occurrence of a field
- Store a zero-length string value in a field
- Select the data type at execution time rather than compile time
If you use the G format, Model 204 expects two items in the buffer for each field; the descriptor byte, and the new or updated field value (there are certain exceptions to this, as described below). The descriptor byte contains the following information:
- Bits 0 and 1 describe the format of the value to be stored or searched:
Bit Meaning 00 DELETE the field specified. If delete is used, Model 204 does not expect a value to follow in the data buffer. If there is another value in the buffer, Model 204 assumes that it belongs to the next edit format. 01 Update or insert this field as an 8-byte FLOAT value. 10 Update or insert this field as a counted STRING value. For a counted string value, the first byte contains the length of the string, followed by the string itself. You can insert a zero-length string into a field using this format. 11 Unused - Bits 2 to 5 are unused.
-
Bit 6 indicates that you want to search for a specific value of a field to update or delete.
When set, bit 6 indicates that the data buffer contains two values, a value to search for, and a value to store in its place. Each value must be preceded by a descriptor.
If the descriptor bit for the second value in the buffer is set to '00' with no data following, the field occurrence is deleted.
- Bit 7 is the bypass field occurrence indicator. If this bit is set, Model 204 bypasses the specified field entirely.
Exceptions to G format usage
Although you can use the G format for all updating calls, there are some circumstances for which searching for specific values (using bit 6) or deleting field values (setting all bits to 0) are incompatible. You cannot use the G format to search by value or delete values for the following types of fields:
- Sort key field
- Hash key field
- %variable (%VARBUF and %VARSPEC parameters)
- When adding fields using the field value(*) format
Changing a specific value
For example, if Joan Darcy is transferred from Portland, OR to Pittsburgh, PA, you can use the G format to change the address in her employment record as follows:
EDIT(G)(G) '10000010''8PORTLAND''10000000''APITTSBURGH' '10000010''2OR''10000000''2PA'
If you change the value of the field to a zero-length string, that value is stored in the field.
Deleting a specific value
If, for example, Hadrian Wall is finally old enough to have his own automobile insurance and can be deleted from his parents' insurance policy, you can delete his field as follows:
EDIT (G) '10000010''7HADRIAN'' B'00000000'
Note: In this case, the first two bits are 0, which indicates a DELETE, the remaining bits are also 0, and there is no second data value in the buffer.
Bypassing a field occurrence
For example, to bypass the third field in the found set of records, use the G format as follows:
EDIT (A)(F)(G)(F) . . . '00000001'
Selecting the data type
To select the data type at execution time, use just the first two bits in the G format. For example, to select only string data:
EDIT(G) '10000000'
Specifying the U format with floating-point values
If you specify the U format with floating-point values, Model 204 interprets the values as nonnumeric strings and stores them as such in Table B.
You cannot access these values as numbers in SOUL; however, retrieval through U EDIT specifications works normally.
Specifying V and M formats
The V format processes field occurrences in the same manner as the M format.
If the field name corresponding to the format in the field name list is specified as fieldname(n), n indicates the position of the first occurrence to be changed. If n is represented by an asterisk (*), all of the values are added as new field occurrences.
Note: The VL format is equivalent to the M format, except that the data values are preceded by a four-byte count rather than by a one-byte count.
Updating a FLOAT field using A, J, L, M, or U formats
When the updated field is defined as FLOAT, Model 204 converts exponential format numbers to floating point using A, J, L, M, or U formats.
When the field is not FLOAT, Model 204 leaves exponential format numbers in their original character form.
Using EDIT format codes for an updating call
The following table describes the edit format codes that can be specified in the edit format with the EDIT option in an IFUPDT, IFSTOR, or IFPUT (updating) call.
| Code | Description |
|---|---|
| A(n) and J(n) | The field value in the data area is n characters long. It is stored with leading and trailing blanks removed. If the final length is 0 after removal of the blanks, the existing field is deleted or is not stored for a new field. |
| B(precision,scale) | The value is in two's complement binary form and is converted to a character string before being stored. precision specifies the number of bits in the numeric value, exclusive of the sign bit. Only two precisions are supported: 15 (halfword) and 31 (fullword). If both precision and scale are omitted, the precision defaults to 15.
scale specifies the number of digits to the right of an implied binary point. The scale must not exceed the precision. If scale is omitted, it defaults to 0, indicating an integer value. If the scale is more than 12, only the high-order 12 fractional bits are converted. Leading integer zeros and trailing fractional zeros are removed from the converted string. An all-zero string is stored as a single zero. |
| COL(n) or COLUMN(n) or |
Skip to character position n of the data area. |
| E(total length, significant digits, fractional digits) |
The value is in exponential format and is converted to the appropriate numeric format before being stored. The significant digits and fractional digits specifications are ignored by IFPUT. They are listed so that an application's IFPUT and IFGET edit formats can be shared. |
| F(n) | The value is in floating-point form. The F specification must be used with FLOAT fields to make floating-point values accessible as meaningful numbers to Model 204.
|
| G | Allows you to:
The G format requires that the data is preceded by a descriptor byte. The G format is described in detail in Using the G format. |
| L | The first byte of the data is a hexadecimal number that represents the length of the data bytes that follow. The value is stored without the length byte. Leading binary zeros are eliminated; leading and trailing blanks are not eliminated. If the final length is 0, the field is deleted; if the field is new, it is not stored.
For example, X'03C1C2C3' is equivalent to 'ABC'; X'04C1C2C340' includes the trailing blank in the stored value. |
| L(n) | The value is n characters long. Leading binary zeros (X'00') are eliminated; leading and trailing blanks are not eliminated. If the final length is 0, the existing field is deleted. If the field is new, it is not stored. |
| M(n) | The first data byte contains the number of value occurrences. The values that follow are each n characters long. Leading binary zeros are eliminated. |
| P(precision,scale) | The value is in packed-decimal form and is converted to a character string before being stored. precision specifies the number of digits (not bytes) in the numeric value, exclusive of the sign. The maximum precision for a packed-decimal field is 15. If both precision and scale are omitted, precision defaults to 5.
scale specifies the number of digits to the right of an implied decimal point. The scale must not exceed the precision. If scale is omitted, it defaults to 0, indicating an integer value. Leading integer zeros and trailing fractional zeros are removed from the converted string. An all-zero string is stored as a single zero. No input validation is done, allowing nonnumeric values to be stored. |
| U(n) | The field value in the data area is n characters long (n is less than 255). It is not stripped when it is stored. This format cannot be used to delete an old occurrence of a field. |
| V | Collect all occurrences of a field into a single data area. The area begins with a four-byte count of the number of data values in the area. The format of the values is determined by the second edit format, which must be specified immediately after the V. An example and a summary of restrictions is included below. |
| X | Same as X(1). See X(n). |
| X(n) | Skip n characters in the data area. |
| Z(precision,scale) | The value is in zoned-decimal form. Precision, scale, and conversion rules are identical to the P format. |