HLI: Model 204 fields and variables

Overview

This topic describes two basic Model 204 database constructs, fields and variables, for application programmers who are using the Host Language Interface facility.

See the HLI function summary for more information about HLI function calls.

See Field design and Using variables and values in computation for more information about Model 204 fields and variables.

Field names and values

The smallest addressable element of the Model 204 system is the field. To identify and retrieve data, assign meaningful names, such as AGE, ADDRESS, OCCUPATION, and SEX, to fields. Each Model 204 file can have as many as 4000 different field names defined.

Model 204 stores each field as a name=value pair, for example, SEX=FEMALE and SEX=MALE. Field name=value pairs are variable in length to provide for file compression and text processing capabilities.

The structure of a Model 204 record does not limit the number of occurrences of a field in a record. Fields that appear more than once in a record (for example, CHILD or HOBBY fields) are known as multiply occurring fields. When referring to a field that is multiply occurring, specify whether, for example, the first, fifth, or all occurrences of the field are being addressed.

Rules for naming fields

The following rules apply for naming Model 204 fields:

• A field name must begin with a letter and can be up to 255 characters in length.
• Except for the following characters, you can use any word or character (including a space) as part of a field name:

  ?? ?$ ?& @ # ; :

  Note: The at sign (@) and number sign (#) characters are the default terminal correction characters. If you specify some other characters in the ERASE and FLUSH parameters, the restriction on using @ and # in a field name applies instead to the symbols that you specify.

• When more than one consecutive space appears in a field name, Model 204 ignores the extra spaces.
• Any reserved word or operator can be:
  • Part of an unquoted string, as long as it is not surrounded by spaces.
    For example, ZCOUNT is valid; Z COUNT is invalid.
  • Part of a quoted string, as long as it does not stand alone.
    For example, A 'OR' B is valid; 'OR' is invalid.

  For more information about quotation marks, see Using quotation marks.

  The following terms have special meaning in the Model 204 system, and they are reserved. To avoid errors, do not use reserved terms when forming field names and values.

  AFTER	ALL	AND	AT
  BEFORE	BY	COUNT	EACH
  EDIT	END	FROM	IN
  IS	LIKE	NOR	NOT
  OCC	OCCURRENCE	OR	RECORD
  RECORDS	TAB	THEN	TO
  VALUE	VALUES	WHERE	WITH
  EQ     GE	GT     LE	LT	NE

• Any of the following reserved characters, if embedded in a field name, must be part of a string enclosed in quotation marks. Avoid the following characters when forming field names and values:

  $	*	/	#	@	=
  <	>	;	:	,	ÿ
  + (plus sign)		- (minus sign)		... (period in series)
  (	)

Examples of valid field names

The following examples are valid Model 204 field names:

A345 ANNUAL.%INTEREST A' = B'

Examples of invalid field names

The following examples are invalid Model 204 field names:

%INTEREST YEAR TO DATE USE COUNT NAME?? 'VALUE'

Forming field values

The following rules apply for forming Model 204 field values:

• A field value can be up to 255 characters in length.
• Except for the following characters, you can use any word or character (including a space) as part of a field value:

  ?? ?$ ?& @ # ; :

  Note: The restriction on using at sign (@) and number sign (#) characters is the same as for field names. See Rules for naming fields.

• When more than one consecutive space appears in a field value, Model 204 ignores the extra spaces.
• When using a reserved word or character in a value used with the EDIT form of IFUPDT or IFPUT or a %variable assignment, do not enclose the value with quotation marks.
• Enclose values that contain reserved words with quotation marks in all other instances (such as with IFFIND).

Examples of valid field values

The following examples are valid values for Model 204 fields:

PARENTS='MARY AND JOHN SMITH' CITY=BOSTON

In these examples, PARENT and CITY are fields; their values appear to the right of the equal sign (=).

Using quotation marks

The following rules apply for using quotation marks:

• When quotation marks are used, an even number is required.
• A pair of single quotation marks denotes a quoted string, for example, 'TEXT'.
• Model 204 stores and uses quoted strings with quotation marks dropped.
• Model 204 replaces a pair of consecutive single quotation marks inside a quoted string with a single quotation mark upon storing or printing the string.

  For example, the quoted strings shown below on the left result in the output on the right:

  Quoted string	Output
  PRINT 'FATHER''S NAME'	FATHER'S NAME
  PRINT ''AND''	'AND'

• Model 204 converts a ' ' (a pair of consecutive single quotation marks that is not included in a quoted string) to a character string of zero length, called a null string.

See Request composition rules for more information about quotation marks.

Field definitions and attributes

Defining fields

To define a new field, use IFDFLD.

To redefine a field, use IFRFLD, which requires Model 204 file manager privileges.

When using IFDFLD or IFRFLD, you need a knowledge of field attributes.

Note: Field definition is usually the responsibility of the Model 204 file manager. Technical Support recommends that a site restrict tasks to selected personnel. This restriction prevents the proliferation of unnecessary fields and guarantees consistency of field names and field types among files in a group.

When to assign field attributes

You assign field attributes when you:

• Initially load a file
• Add a new field name to an established file (IFDFLD)
• Redefine a field description (IFRFLD)

  Note: If you define a field but do not specify field attributes, Model 204 assigns default attributes.

Once a field attribute has been assigned, it applies whenever the field name appears in the file.

Field attributes

You can assign each field in a Model 204 file certain field attributes, including storage and security options, based on the characteristics of the data.

You can combine field attributes and options. The combination of attributes for a field governs the operational characteristics of a field and the amount of space required to store the field value internally. The operational characteristics and storage characteristics of a field are usually independent considerations.

The following sections briefly describe Model 204 field attributes. For complete information about field attributes, see Field design.

Operational characteristics of a field

Use the following field attributes to control the operational characteristics, that is, how the field is used:

Field attribute	Meaning
KEY	KEY fields provide quick access to data. Pointers to records that contain specific values of KEY fields are maintained in the index area. You can specify fields designated as KEY in record selection specifications to retrieve records based on index entry. Use IFFIND to select KEY fields. See NUMERIC RANGE and NONRANGE inconsistencies for information about KEY inconsistencies.
NON-KEY	NONKEY fields do not contain pointers in the index area. You can use NONKEY fields to retrieve records with IFFIND, but selection is performed by sequential search and is less efficient than with KEY fields. See NUMERIC RANGE and NONRANGE inconsistencies for information about NONKEY inconsistencies.
NUMERIC RANGE or RANGE	NUMERIC RANGE or RANGE fields contain certain numeric values. The index area contains multiple pointers to fields within a range of values. You can specify numeric range retrievals for these fields. NUMERIC RANGE fields cannot be defined to a file with the First-Normal Form (1NF) file model option set. See NUMERIC RANGE and NONRANGE inconsistencies for information about NUMERIC RANGE inconsistencies.
NONRANGE	Model 204 does not store multiple pointers for NONRANGE fields. You can specify numeric range retrievals for these fields, but the selection is less efficient than for NUMERIC RANGE fields. See NUMERIC RANGE and NONRANGE inconsistencies for information about NONRANGE inconsistencies.
ORDERED	Fields designated as ORDERED make up the Ordered Index. Model 204 maintains the values of Ordered Index fields in a particular collating sequence for alphabetic, alphanumeric, and numeric range retrievals to make range retrievals more efficient. An ORDERED field can have an order type of either CHARACTER or NUMERIC. You can access file record keys in order.
NONORDERED	NONORDERED is the default if you do not specify the ORDERED attribute when you define a field.
VISIBLE	VISIBLE fields appear in the data area and can be printed, noted, sorted, or used in arithmetic expressions. VISIBLE is the default field designation. See VISIBLE and INVISIBLE inconsistencies for information about VISIBLE inconsistencies.
INVISIBLE	You can use fields designated as INVISIBLE to retrieve records. However, because INVISIBLE fields do not appear in the data area (only in the index areas), you cannot print, note, or sort INVISIBLE fields, or use them in an arithmetic expression. INVISIBLE fields cannot be defined to a file having the First-Normal Form (1NF) file model option set, except in conjunction with the REPEATABLE field attribute. See VISIBLE and INVISIBLE inconsistencies for information about INVISIBLE inconsistencies.
FRV (For Each Value)	FRV fields have a list of all unique values assigned to the field. Special statements are available in SOUL to manipulate the values of FRV fields; IFFDV, IFGETV, and IFFTCH are the corresponding HLI calls.
NON-FRV	NON-FRV fields do not have a list of all unique values for the field.
DEFERRABLE	When you open a file in deferred update mode, Model 204 defers changes to DEFERRABLE field index entries until a later time.
NONDEFERRABLE	Model 204 changes index entries for NONDEFERRABLE fields as the fields are updated, even when you open the file in deferred update mode.
UNIQUE	UNIQUE fields have a uniqueness constraint enforced by the Unique Key. A given field name=value pair occurs in one record in a file. See UNIQUE violations for more information.
NONUNIQUE	NONUNIQUE fields do not have a uniqueness constraint on them.
AT-MOST-ONE	AT-MOST-ONE fields enforce a single occurrence constraint. The field may appear only once in a given record. Note that AT-MOST-ONE is the default for fields defined in a file having the First-Normal Form (1NF) file model option set. See AT-MOST-ONE violations for more information.
REPEATABLE	REPEATABLE fields do not have a single occurrence per record constraint associated with them. See AT-MOST-ONE violations for more information.

Storage characteristics of a field

Use the following field attributes to control the storage characteristics, that is, how Model 204 stores field values in a file:

Field Attribute	Meaning
STRING	Model 204 stores STRING fields as character strings rather than in compressed numerical form.
BINARY	Model 204 compresses BINARY fields for efficient use of storage space. Note that Model 204 cancels a request to store invalid binary data in a file that has the NUMERIC VALIDATION file model option set. See Field-level security violations for information about BINARY violations.
BLOB	Binary strings of type Binary Large Object. Limited to two gigabytes.
CLOB	Character string of type Character Large Object. Limited to two gigabytes.
CODED	Model 204 stores fields designated as CODED as codes in the data area, to reduce storage space requirements, and as character strings in the file dictionary. Model 204 decodes CODED fields internally when retrieving or processing them. You can further designate CODED fields as FEW-VALUED or MANY-VALUED to optimize the coding procedure.
NONCODED	Model 204 stores NONCODED fields as character strings in the data area. See Compression violations for information about NONCODED violations.
FLOAT	Model 204 stores FLOAT fields in floating-point form using IBM hardware floating-point representation. You must supply a LENGTH value with FLOAT to indicate the precision of the floating-point field being defined. Model 204 cancels a request to store invalid floating point data in a file that has the NUMERIC VALIDATION file model option set. See NUMERIC VALIDATION violations for information about FLOAT violations. Refer to the Rocket Model 204 Host Language Interface Reference Manual for a description of floating-point format for IFFTCH, IFUPDT, IFGET, and IFPUT.
FEW-VALUED	Use the FEW-VALUED attribute for a field that has the CODED or FRV attribute and is expected to take on fewer than about 50 different values. Model 204 stores these values in a special section of the file dictionary (Table A).
MANY-VALUED	Use the MANY-VALUED attribute for a CODED or FRV field that is expected to take on at least 50 different values. Model 204 stores these values in a separate special section of the file dictionary (Table A).

Storage options for preallocated fields

Use the following storage options with preallocated fields:

Storage option	Meaning
OCCURS	Indicates the number of times that a field can occur in a record. See OCCURS violations for more information.
LENGTH	Indicates the maximum length of a field. See NUMERIC VALIDATION violations for information about LENGTH violations.
PAD	Indicates the padding character for short fields.

Field updating options

Use the following options to control the type of field updating performed:

Field updating option	Meaning
UPDATE IN PLACE	Causes the field to be changed. Its order in the record is preserved.
UPDATE AT END	Causes the field to be deleted and the new field added at the end of the record when the field is changed.

Field security option

Use the LEVEL option to assign a security level for a field.

Field definitions for group files

The following considerations apply when using fields defined in group file context:

• A given field is not required to have the same properties in all the files of a group. For example, a field can have the NUMERIC RANGE attribute in some files but not in others.
• A field that appears in one or more files of a group need not exist in others.
• If none of the files in a group contain a field name used in a selection specification, Model 204 rejects the specification during compilation.

When inconsistencies in field definition occur among files used in the group context, Model 204 performs certain actions, as described in the following section.

KEY and NONKEY inconsistencies

When you use a field name in selection specifications defined as KEY in some files and NONKEY in others, Model 204 carries out the following actions:

1. Performs a KEY search in files for which the field is defined as KEY.
2. Performs a direct search in files in which the field is defined as NONKEY.

NUMERIC RANGE and NONRANGE inconsistencies

When you use retrieval specifications based on fields that have NUMERIC RANGE or NONRANGE attributes, Model 204 handles them in the same way as for KEY and NONKEY specifications when they occur in a group context.

VISIBLE and INVISIBLE inconsistencies

You can retrieve only VISIBLE fields with IFFTCH, IFGET or IFMORE. If a field is INVISIBLE in one or more files in a group, Model 204 returns a null string for the field, as if it did not exist in the record.

Field access violations

The following types of violations can occur when you attempt to access a field:

• Field-level security
• LENGTH
• OCCURS
• Compression
• UNIQUE
• AT-MOST-ONE

The following sections describe each of these violations related to HLI processing. See Field name variable errors for information about violations with %%variables.

Field-level security violations

Field-level security controls access to the individual fields of a Model 204 file. You can assign a security level to a field by using IFDFLD or IFRFLD.

You can specify any of the following types of field access:

• SELECT, which allows the field to be used in an IFFIND or IFFILE call.
• READ, which allows the value of a field to be examined by IFFTCH, IFGET, or IFMORE.
• UPDATE, which allows the value of a previously stored occurrence of a field to be changed by IFUPDT, IFPUT, IFDVAL, or IFFILE.
• ADD, which allows new occurrences of a field to be added by IFUPDT, IFPUT, or IFFILE.

Model 204 handles field-level violations

When you attempt to access a field having field-level security, access succeeds only if your user access level is equal to or greater than the level defined for the field. Otherwise, a field-level security violation occurs.

Model 204 returns a completion code of 4 for a field-level security violation and an error message. Note that you can retrieve the error message using IFGERR.

In general, Model 204 handles field-level security violations differently depending on the type of access violation and whether it occurs in file or group context.

Model 204 takes different actions for an access violation depending on the type of access attempted when the violation occurred:

• For SELECT or READ access, Model 204 performs the operation as if the field did not exist.
• For UPDATE or ADD access, Model 204 cancels the HLI call and returns a completion code of 4 to the HLI program.

Although a user's access rights are fixed for a group, the field's access level can vary from file to file. This might make access to a field legal in some files and illegal in others. Model 204 rejects a HLI call that contains a field name reference under the following conditions:

• In file context, if the access is not allowed in the file.
• In group context, if the access is not allowed in any file in the group.

  Note: Use IFFLS in your HLI program to check for field-level security violations before they occur.

Field-level violations for IFFTCH, IFUPDT, IFGET, and IFPUT

Model 204 treats HLI calls that compile IFGET (or IFMORE) and IFPUT specifications in a special way, because a specification compiled by IFGET (or IFMORE) can be executed by IFPUT, and vice versa. The same is true for IFFTCH and IFUPDT specifications on a multiple cursor IFSTRT thread.

If an HLI thread has READ, UPDATE, or ADD access to a field, you can reference the field using IFFTCH or IFUPDT on a multiple cursor IFSTRT thread, or IFGET or IFPUT on a single cursor IFSTRT thread.

For field-level violations involving IFFTCH, IFUPDT, IFGET, or IFPUT, Model 204 performs the following actions:

• If a violation occurs during IFFTCH, IFGET, or IFMORE processing, Model 204 returns a null value for the affected field or fields and continues processing the call.
• For the retrieve-all-fields form of the data specification with IFFTCH or IFGET, Model 204 returns only fields for which the user has READ access.
• If a violation occurs during IFUPDT or IFPUT processing, Model 204 stops processing the call and returns a completion code of 4 to the HLI program.

LENGTH violations

A field can be defined as preallocated and having a maximum LENGTH m. Space for this length is preallocated in each record in a file, and this space cannot be expanded.

Note: If a field is defined as having a LENGTH of m, that you can assign that field only values that are between 1 and m bytes long.

Model 204 rejects any attempt to store values greater than the specified maximum length with IFUPDT, IFSTOR, IFPUT, or IFBREC, by canceling the call and returning a completion code of 4 to the HLI program.

Model 204 treats any attempt to locate or delete unacceptable values as references to nonexistent values with the following actions:

• For IFFIND, the selection criteria fail to locate any records.
• IFDVAL does not delete any fields.

OCCURS violations

If a field is defined as occurring a particular number of times, that is, OCCURS n, it can be stored at most n times in any record.

Model 204 cancels the call and returns an error completion code to the HLI program for either of the following conditions:

• If the HLI program issues either IFUPDT or IFPUT and attempts to add a new occurrence of an OCCURS n field to a record that already contains the maximum number.
• During processing, if Model 204 encounters a nonnumeric value in an OCCURS FLOAT field.

Compression violations

If a field is defined as having the attributes OCCURS n, BINARY, and NONCODED, only compressible values can be stored in it.

A small amount of space is preallocated for such a field. A compressible value is a decimal integer of as many as nine digits, but without a plus sign, leading zeroes, embedded blanks following a minus sign, or a decimal point.

Note: If you use IFUPDT or IFPUT and attempt to store an incompressible value in an OCCURS n, BINARY, NONCODED field, Model 204 cancels the call and returns a completion code of 4 to the HLI program.

UNIQUE violations

If a field is defined as UNIQUE, only one record in the file can contain any given value of that field.

Note: If you use IFUPDT, IFSTOR, IFPUT, or IFBREC and attempt to store the same value of a UNIQUE field in another record, Model 204 cancels the call and returns a completion code of 200 to the HLI program.

If a completion code of 200 is returned, use the IFEFCC call to determine which records are creating the uniqueness violation.

NUMERIC VALIDATION violations

During processing, if Model 204 encounters invalid data for BINARY and FLOAT numeric field types, Model 204 cancels the call and returns an error code to the HLI program.

AT-MOST-ONE violations

If a field is defined as AT-MOST-ONE, only one occurrence of that field can be stored in a particular record.

Note:If the HLI program issues a call to IFSTOR, IFUPDT, or IFPUT, and attempts to store more than one (that is, a second) occurrence of the field within a particular record, Model 204 cancels the call and returns a completion code of 202 to the HLI program.

If a completion code of 202 is returned, use the IFEFCC call to determine which records are creating the AT-MOST-ONE violation. See the Rocket Model 204 Host Language Interface Reference Manual for information about IFEFCC.

Using %variables

A %variable is an entity whose name can substitute another value or expression in a SOUL statement or HLI program. %Variables can be used any place in SOUL that a value can be used.

You can change the value of a variable at any time by assigning it a new value. You assign one or more %variables in an HLI call by specifying the %variable parameters (%variable buffer and %variable specification) in the parameter list. See below for more information about these %variable parameters.

The %variable option is available for use with the following IFSTRT calls:

Compile and execute:	Execute-only:
IFBREC	--
IFCLST	--
IFCTO	IFCTOE
IFFAC	IFFACE
IFFDV	IFFDVE
IFFIND	IFFINDE
IFFNDX	IFFNDXE
IFFTCH	IFFTCHE
IFFWOL	IFFWOLE
IFGET	IFGETE
IFGETX	IFGETXE
IFMORE	IFMOREE
IFMOREX	IFMORXE
IFOCC	IFOCCE
IFOCUR	IFOCURE
IFPUT	IFPUTE
IFSKEY	IFSKYE
IFSORT	IFSRTE
IFSTOR	IFSTRE
IFUPDT	IFUPDTE

Note: Except for IFBREC and IFCLST, the IFSTRT thread calls listed above are used with the Compiled IFAM facility. See HLI: IFSTRT processing for information about the Compiled IFAM facility.

Specifying a %variable name

The following rules apply for specifying a %variable name:

• The first character of the %variable name must be a percent sign (%).
• Any combination of letters and numbers is valid.
• No embedded blank or colon (:) characters are allowed in the name.
• You can repeatedly reassign a %variable name. However, each assignment affects all specifications in which the %variable is referenced.

Example of when to use a %variable

Use %variables when your HLI application program performs similar and successive data retrievals.

For example, an IFFIND call frequently appears inside an IFGET loop. The IFFIND uses the value retrieved by the IFGET as part of the selection criteria.

To cross-reference without using the %variable facility, you must code your program to move the value retrieved by the IFGET into the IFFIND selection criteria. Since the IFFIND specification is modified during execution, it cannot be compiled and saved from one call to the next.

In contrast, using the %variable facility you can use %variables to replace field values in IFFIND criteria that are not known at compilation time.

For example, a specification that is referred to in an IFFIND call might have the following form:

LAST NAME=%NAME AND RECTYPE=CHILD;END;

Using this specification, during the execution of IFFIND, the appropriate last name substitutes for %NAME. In the next execution of IFFIND, you can specify a new last name or you can reuse the old one. See Specifying the %variable parameters for information about specifying %variables in an HLI call.

Specifying the %variable parameters

You assign one or more %variables in an HLI call by specifying the %variable input parameters, that is, %variable buffer and %variable specification, in the parameter list.

Note that if you specify one, you must specify the other. Specify each of the %variable parameters as a character string, whose maximum length is the input buffer size. Refer to the functions in HLI functions to see each function's parameter list.

The %variable buffer parameter (%VARBUF in the parameter list descriptions) contains the values to be assigned to the %variables that are used by the call.

The %variable specification (%VARSPEC in the parameter list descriptions) describes the format of the data contained in the %variable buffer and, in some cases, the list of %variables to be assigned. The %variable specification follows the syntax of the LIST, DATA, or EDIT specifications used with IFUPDT or IFPUT.

See Assignment of %variables for more information about the %variable specification.

Using %variables in EDIT and LIST specifications

You can use a %variable in the field name list of an EDIT or LIST specification for the IFFTCH, IFGET, IFGETX, IFMORE, IFMOREX, IFPUT, IFSTOR, and IFUPDT calls. See the specific calls in the Rocket Model 204 Host Language Interface Reference Manual for more details.

Example of using a %variable

The following excerpt shows how to use a %variable in an IFFIND call to retrieve a series of Social Security numbers from records. In this example, the IFFIND is coded inside a program loop that retrieves records.

The sample COBOL program issues the following IFFIND call:

CALL "IFFIND" USING RETCODE,FDSPEC,FDNAME,SSN,SSNEDIT.

where:

• RETCODE is the Model 204 completion code.
• FDSPEC is the name of a data area that contains selection criteria for IFFIND (also known as the FIND specification).
• FDNAME is the name of the compilation to be used by subsequent executions.
• SSN specifies the %variable buffer parameter; SSN is the name of a data area that contains the value of the Social Security number, which is assigned to the %variable %SSN.
• SSNEDIT specifies the %variable specification parameter; SSNEDIT describes the format of the SSN data area.

  The DATA DIVISION of the sample COBOL program contains the following definitions of the IFFIND parameters:

  WORKING-STORAGE SECTION. 01 CALL-PARMS COMP SYNC. 02 RETCODE PICTURE 9(5). . . . 01 ALPHA-PARMS. 02 FDSPEC PICTURE X(18) VALUE 'SOCSECNO=%SSN;END;'. 02 FDNAME PICTURE X(5) VALUE 'FIND;'. 02 SSN PICTURE 9(9). 02 SSNEDIT PICTURE X(17) VALUE 'EDIT(%SSN)(A(9));'. . . . PROCEDURE DIVISION. CALL "IFFIND" USING RETCODE, FDSPEC, FDNAME, SSN, SSNEDIT. . . .

Assignment of %variables

Values in the %variable buffer are assigned to %variables depending on what type of %variable specification you use. You can specify the %variable specification with a LIST, DATA, or EDIT format as is used with IFUPDT or IFPUT.

Model 204 assigns %variables in the following ways:

• For a LIST specification, the format is:

  LIST(%variable1,%variable2, ...);

  where, each value in the %variable buffer is assigned to the corresponding %variable in the list. The values in the %variable buffer are stored in the following form:

  'value1''value2'...

• For a DATA specification, the format is:

  DATA;

  where, explicit %variable assignments are included in the %variable buffer parameter in the following form:

  %variable1=''value1'; %variable2=''value2'...

• For an EDIT specification, the format is:

  EDIT(%variable1,%variable2,...)(format1,format2,...);

  where, each value in the %variable buffer is assigned to the corresponding %variable in the list according to the corresponding format. See Example of using a %variable for an example of an EDIT specification using a %variable.

Assignment of %variables for HLI threads

Each HLI thread has its own set of %variables.

Upon the initial reference to a %variable on an HLI thread, Model 204 assigns a null string. The %variable retains the null value until an explicit assignment is made.

Note: If you attempt to assign a value to a previously unreferenced %variable, Model 204 displays a NAME LIST SYNTAX ERROR message.

After a value is assigned to a %variable, the value and the format are carried from one HLI call to the next, making repeated assignment unnecessary for values that do not change. To avoid redundant processing, specify only those %variables in an HLI call that take on new values.

Using field name variables

Field name variables are extensions of percent variables (%variables).

Field name variables enable you to refer indirectly to field names, thereby enabling HLI calls to be generalized. Using field name variables, you specify the actual field names used by a particular HLI call when you execute your HLI program.

Specifying a field variable name (%%variable)

The same rules apply for specifying a field variable name as for a %variable name except that the field variable name begins with two percent signs(%%). For example, %%FIELD can be used to specify a field name variable.

See Specifying a %variable name for naming rules.

Note: A %variable and a %%variable that have identical names are actually the same variable. When the variable is used in a %variable context, for example as the value in a FIND specification, it takes the %name form. Or, if the variable is used in a field name context, for example as part of a field name list in a GET specification, it takes the %%name form.

In the latter case, the value of the variable at the time that the GET specification is executed is substituted in the specification and is then treated as a field name. When a value is assigned to a field name variable, the name of the value that should be assigned to the field name variable is actually a percent variable, that is, a %name rather than a %%name.

When to use a field name variable

You can reference a field name variable in any of the following IFSTRT thread calls:

• IFCTO
• IFFIND
• IFFNDX
• IFFTCH
• IFGET
• IFMORE
• IFOCC
• IFPUT
• IFUPDT

You can specify a %%variable in a HLI call anywhere you would normally reference a field name. You can also specify a %%variable in a DATA input specification in an IFUPDT or IFPUT call.

Example of using %%variables

The following COBOL code excerpt contains two different record types. The types have nearly all fields in common, but they differ in the following ways:

• Record type A has a STATUS field, while record type B has a PERFORMANCE field.
• Record type A has a SALARY field, while record type B has a COMPENSATION field.

This COBOL example illustrates field name variable processing in the following way:

• In EDITLIST-1, the field name variables (%%STATUS and %%SALARY) represent the actual field names in the two record types.
• The IFGETC call compiles the GET specification. This specification is then executed by the two IFGETE calls.
• The field names are assigned by EDITLIST-2, depending on the record type encountered. For record type A, field names are STATUS and SALARY; for record type B, field names are COMPENSATION and PERFORMANCE.

  01 WORK-REC. 02 REC-TYPE PIC X. 02 WORD-SSN PIC 9(9). 02 WORK-NAME PIC X(30). 02 WORK-BDATE PIC 9(6). 02 WORK-SCDATE PIC 9(6). 02 FILLER PIC X(2). 02 WORK-GRADE PIC 9(2). 02 WORK-STEP PIC 9(2). 02 WORK-STATUS PIC X(2). . . . 01 ALL-PARMS. 02 RETCODE PIC 9(5) COMP SYNC. 02 CNAME PIC X(8) VALUE 'FTCHREC;'. 02 DIR1 PIC 9 COMP SYNC VALUE 1. 02 DIR0 PIC 9 COMP SYNC VALUE 0. 02 EMPCUR PIC X(7) VALUE 'EMPCUR;'. 02 REC-A PIC X(13) VALUE 'STATUS SALARY'. 02 REC-B PIC X(24) VALUE 'PERFORMANCE COMPENSATION'. . . . 01 PERCENT-PARMS. 02 EDITLIST-1 PIC X(110) VALUE 'EDIT (REC-TYPE,SSN,NAME,BDATE,SCDATE,GRADE, STEP,%%STATUS,%%SALARY) (A(1),A(9),A(30),2A(6),X(2),2J(2),A(2),A(8));'. 02 EDITLIST-2 PIC X(36) VALUE 'EDIT (%STATUS,%SALARY)(A(11),A(12));'. . . . CALL 'IFFTCH' USING RETCODE,WORK-REC,DIR1,EMPCUR, CNAME,EDITLIST-1. . . . IF REC-TYPE='A' THEN CALL 'IFFTCH' USING RETCODE,WORK-REC,DIR0,EMPCUR, CNAME,REC-A,EDITLIST-2. . . . IF REC-TYPE='B' THEN CALL 'IFFTCH' USING RETCODE,WORK-REC,DIR0,EMPCUR, CNAME,REC-B,EDITLIST-2. . . .

  Field name variable errors

  When you use a field name variable, Model 204 defers validity checks, which would normally be performed when a specification is compiled, until the specification is executed and the actual field name is filled in.

  You might encounter the following errors for field name variables:

  • If the field name variable specified in an IFFIND call is not valid, Model 204 does not execute the call.
  • If a missing field name is encountered when processing IFUPDT or IFPUT, Model 204 aborts processing of the field name list and returns a completion code of 4.
  • If a missing field name is encountered when processing IFFTCH or IFGET, Model 204 returns a null string value as if the field were missing from the record.

  See also

  • HLI: Threads
  • HLI: IFSTRT processing
  • HLI: IFDIAL processing
  • HLI: Using Model 204 completion return codes
  • HLI: Model 204 parameters
  • HLI: Model 204 files and records
  • HLI: Model 204 fields and variables
  • HLI: Find criteria for Model 204 data
  • HLI: Locking behavior of HLI calls
  • HLI: Record locking conflicts
  • HLI: Model 204 security
  • HLI: Model 204 tables
  • HLI: Model 204 data sets in HLI jobs
  • HLI: IFAM2 CICS processing
  • HLI: Transactions
  • HLI: Model 204 recovery and checkpoints