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.

Examples of numeric edit format conversion

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.

EDIT format codes used with a 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. If n is 16, the value is truncated or expanded to an extended precision, floating-point number (occupies 16 bytes and holds up to 31 significant digits). If n is 8, the character string is truncated or expanded to a long precision, floating-point number (occupies 8 bytes and holds up to 15 significant digits). If n is 4, the character string is first truncated or expanded to a long precision, floating-point number and is then rounded and truncated to a short precision number (occupies 4 bytes and holds up to 6 significant digits). 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: Rounding occurs after each arithmetic operation involving floating-point numbers. If the field is KEY, the value to be indexed is rounded. If the field is used in a direct Table B search in an IFFIND call, the value to be searched for is rounded to long precision (8 bytes), and each field accessed in Table B is likewise rounded before comparison. If the field will be used in a sort key, the value is rounded before being concatenated to the key. If the source number is a floating-point number longer than the field or %variable into which it is stored, the source number is rounded and truncated so that it correctly fits. If the source number is a floating-point number shorter than the field, the source number is rounded to its maximum significant digits and expanded with zeros to the longer precision.
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.

EDIT format codes used with an 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 POS(n)	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. If n is 16, the value is extended precision (occupies 16 bytes and holds up to 31 significant digits). If n is 8, the value is long precision (occupies 8 bytes and holds up to 15 significant digits). If n is 4, the value is short precision (occupies 4 bytes and holds up to 6 significant digits). Values to be stored in FLOAT fields whose lengths differ from the length defined for the FLOAT field are truncated or rounded to the defined length without a cancellation of the call.
G	Allows you to: Select the data type at execution time Bypass an occurrence of a specific field at execution time Change or delete specific field=value pairs 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.

See also

• Introduction to the HLI facility
• HLI: Job design factors
• HLI: Job requirements
• HLI: Coding conventions
• HLI: Function summary
• HLI functions
• HLI: Field formatting options for HLI calls
• HLI: Model 204 completion and ABEND codes
• HLI: IFAM1 job program examples
• HLI: IFAM2/IFAM4 job program examples