Host structures in COBOL

A COBOL host structure is a named set of host variables that are defined in your program's WORKING-STORAGE SECTION or LINKAGE SECTION.

Requirements: Host structure declarations in COBOL must satisfy the following requirements:
  • COBOL host structures can have a maximum of two levels, even though the host structure might occur within a structure with multiple levels. However, you can declare a varying-length character string, which must be level 49.
  • A host structure name can be a group name whose subordinate levels name elementary data items.
  • If you are using the Db2 precompiler, do not declare host variables or host structures on any subordinate levels after one of the following items:
    • A COBOL item that begins in area A
    • Any SQL statement (except SQL INCLUDE)
    • Any SQL statement within an included member
    When the Db2 precompiler encounters one of the preceding items in a host structure, it considers the structure to be complete.

When you write an SQL statement that contains a qualified host variable name (perhaps to identify a field within a structure), use the name of the structure followed by a period and the name of the field. For example, for structure B that contains field C1, specify B.C1 rather than C1 OF B or C1 IN B.

Host structures

The following diagram shows the syntax for declaring host structures.

Read syntax diagramSkip visual syntax diagramlevel-11 variable-name.level-223var-1numeric-usage.PICTUREPICISpicture-stringinteger-decimal-usage.char-inner-variable.varchar-inner-variablesvargraphic-inner-variablesUSAGEISSQL TYPE ISROWID.USAGEISSQL TYPE ISTABLE LIKEtable-nameAS LOCATOR.USAGEISLOB data type.4
Notes:
  • 1 level-1 indicates a COBOL level in the range 1–47.
  • 2 level-2 indicates a COBOL level in the range 2–48.
  • 3 For elements within a structure, use any level 02 through 48 (rather than 01 or 77), up to a maximum of two levels.
  • 4 Using a FILLER or optional FILLER item within a host structure declaration can invalidate the whole structure.

Numeric usage items

The following diagram shows the syntax for numeric-usage items that are used within declarations of host structures.

Read syntax diagramSkip visual syntax diagramUSAGEISCOMPUTATIONAL-1COMP-1COMPUTATIONAL-2COMP-2VALUEISconstant

Integer and decimal usage items

The following diagram shows the syntax for integer and decimal usage items that are used within declarations of host structures.

Read syntax diagramSkip visual syntax diagramUSAGEISBINARYCOMPUTATIONAL-4COMP-4COMPUTATIONAL-5COMP-5COMPUTATIONALCOMPPACKED-DECIMALCOMPUTATIONAL-3COMP-3DISPLAYNATIONALSIGNISLEADING SEPARATECHARACTERVALUEISconstant

CHAR inner variables

The following diagram shows the syntax for CHAR inner variables that are used within declarations of host structures.

Read syntax diagramSkip visual syntax diagramPICTUREPICISpicture-string USAGEISDISPLAYVALUEISconstant

VARCHAR inner variables

The following diagrams show the syntax for VARCHAR inner variables that are used within declarations of host structures.

Read syntax diagramSkip visual syntax diagram491 var-2PICTUREPICISS9(4)S9999USAGEISBINARYCOMPUTATIONAL-4COMP-4COMPUTATIONAL-5COMP-5COMPUTATIONALCOMPVALUEISnumeric-constant . 
Notes:
  • 1 The number 49 has a special meaning to Db2. Do not specify another number.
Read syntax diagramSkip visual syntax diagram49var-3PICTUREPICISpicture-string USAGEISDISPLAYVALUEIScharacter-constant . 

VARGRAPHIC inner variables

The following diagrams show the syntax for VARGRAPHIC inner variables that are used within declarations of host structures.

Read syntax diagramSkip visual syntax diagram49var-4PICTUREPICISS9(4)S9999USAGEISBINARYCOMPUTATIONAL-4COMP-4COMPUTATIONAL-5COMP-5COMPUTATIONALCOMPVALUEISnumeric-constant . 
Read syntax diagramSkip visual syntax diagram49var-5PICTUREPICISpicture-string1 USAGEISDISPLAY-123NATIONALVALUEISgraphic-constant . 
Notes:
  • 1 For fixed-length strings, the format of picture-string is G(m) or N(m) (or, m instances of GG...G or NN...N), where 1 <= m <= 127; for other strings, m cannot be greater than the maximum size of a varying-length graphic string.
  • 2 Use USAGE NATIONAL for only Unicode UTF-16 data. In the picture-string for USAGE NATIONAL, you must use N in place of G.
  • 3 You can use USAGE NATIONAL only if you are using the Db2 coprocessor.

LOB variables, locators, and file reference variables

The following diagram shows the syntax for LOB variables, locators, and file reference variables that are used within declarations of host structures.

Read syntax diagramSkip visual syntax diagramSQL TYPE ISBINARY LARGE OBJECTBLOBCHARACTER LARGE OBJECTCHAR LARGE OBJECTCLOBDBCLOB(lengthKMG)BLOB-LOCATORCLOB-LOCATORDBCLOB-LOCATORBLOB-FILECLOB-FILEDBCLOB-FILE

LOB variables and file reference variables for XML data

The following diagram shows the syntax for LOB variables and file reference variables that are used within declarations of host structures for XML.

Read syntax diagramSkip visual syntax diagramSQL TYPE IS XML ASBINARY LARGE OBJECTBLOBCHARACTER LARGE OBJECTCHAR LARGE OBJECTCLOBDBCLOB(lengthKMG)BLOB-FILECLOB-FILEDBCLOB-FILE

Example

In the following example, B is the name of a host structure that contains the elementary items C1 and C2. 
01 A
  02 B
    03 C1 PICTURE ...
    03 C2 PICTURE ...
To reference the C1 field in an SQL statement, specify B.C1.