Images

Overview

This article describes images, a feature of SOUL that allows:

• A request to read and process non-Model 204 files, that is, sequential and VSAM files, and terminal input, such as a Host Language IFDIAL thread
• A request to write to sequential files and terminals
• The creation of formatted blocks of storage that can be used to build records or to process data that is not in a format automatically recognized by Model 204

Terminology

Before reviewing the capabilities and requirements of images, you should be familiar with the following terms that are used throughout this discussion:

Term	Definition
Array	Ordered arrangement of data elements. Multiple occurrences of an item or a group of items.
Block	A contiguous storage area into which a record is read or from which a record is written. Also, block can be a contiguous storage area in which data can be manipulated.
Image	A description of the format of data in a block.
Item	An individual string or number in an image.

Global images

Global images provide a means for passing image data from one request to another, and for efficiently managing more than one image in one request.

Although there are some differences in the way you use a Declare Image statement, you generally define and use global images the same as you do non-global images. See Global images and screens where a discussion of global screens, menus, and images begins.

Using images

See Global images and screens for a discussion of global images.

Reading external files or terminal input

Input sources

The image feature lets a request read and process records from the following sources of input:

Input sources	Description
Sequential or VSAM files	Any number of sequential or VSAM files can be read and processed. If VSAM files are used, the files must be keyed sequential (KSDS). KSDS files can be accessed using an alternate index path. For more information on the types of files and keys that can be used, see the DEFINE DATASET command.
Terminal	Terminal input can be read and processed. A terminal can consist of the physical device on which the request is run, or a User Language connection that has been made from a Host Language application program by using the IFDIAL function.

External records

Records read from sequential or VSAM files and data passed from the terminal are referred to as external records in this discussion to distinguish them from Model 204 records.

The format of the external record is described by a structure called an image. Multiple descriptions of a record are allowed, as discussed later in this article. SOUL statements can refer to each item described in the image definition.

Reading records into an image

SOUL statements, which are documented beginning with Processing images, let the request open the file, read records into the image, and close the file.

For keyed VSAM files, the request can position the file to read sequentially starting with any record in the file.

Writing to sequential files or a terminal

The image feature lets a request write records to any number of sequential files or to a terminal. This capability allows multiple output files and reports to be written by a single pass of the database.

Note: Only printable characters of a record are displayed on a physical terminal device. Therefore, images used to write to a physical terminal device should be defined with string items only.

Defining storage blocks

You can define the data in a block of storage as an image.

The image definition can consist of item definitions as well as definitions of areas in the block that do not need to be accessed. Items in the image can be filled with constants, %variables, fields from a Model 204 record, screen items, items from the current block or another block, and expressions.

Each item defined in the image can be referred to by SOUL statements.

Possible uses

In addition to sequential file, VSAM file, or terminal I/O processing, the ability to manipulate a block of storage has several other uses. For example, you can:

• Construct print lines by filling in items in one or more images at various points in a request. Once the print lines are complete, you can print the lines.
• Copy into an image fields in Model 204 records that have formats not directly recognized by User Language; the individual parts of the field then can be accessed as image items. For example, if the user wants to use packed decimal data that is stored in a Model 204 field, the data can be moved into an image item and used directly. This eliminates the need to use the $Pack function to convert the data prior to its use.
• Store blocks of data of up to 255 bytes as a single field, copied to an image, and the parts of the block can be referred to separately. Data that is stored as a single, large field, for example, a line of text, can be moved into an image that defines the data as one or more items. The items then can be referred to separately.
• Pass data from one request to another.
• You can manipulate more than one image at a time in an application, for example, in a Horizon application involving simultaneous conversations.
• You can use images to structure the local working storage of a request in a more disciplined manner than is possible with %variables.

Defining an image

Managing blocks

You must define the layout of an image block before it can be used by the request.

A block is defined by one or more images that describe the data in the block.

Images describe blocks of data up to 32,767 bytes in length.

Define an image before referring to it

In a request, an image definition must precede any references to the image.

Understanding how data is described by images

To design applications using images, you can review the following summary of how images are used to describe different views of the data is provided below:

• Using images, the application can access any piece of data in the block. As many as 255 images can describe the same block.
• Although a single request can contain more than one block of images, the total number of images for all blocks within each request cannot exceed 256 images (version 7.6 and earlier) or 4095 images (version 7.7 and later).
• You can define multiple images to provide different views of the same data. This is similar to the COBOL capability to REDEFINE a piece of storage. The multiple image capability enables the request to read in a record, determine the format of the data in the record, and access different data items in the record according to format.
• You can define the image items as strings or numbers. Numbers can have binary, floating point, packed decimal, zoned decimal, and exponential formats. Model 204 automatically handles all data type conversions when referring to image items.
• You can define fixed and variable length arrays within an image. Each array element can contain one or more items. Arrays can be nested up to 255 levels deep.
• You can define image items precisely or their length can be determined during evaluation. Similarly, the number of array occurrences can be determined during evaluation. This capability allows the request to handle all types of data structures.

Image components

Each block definition must begin with an Image statement and end with an End Image statement. Between these statements, the following components are used to describe the contents of the block:

• Image definitions
• Item definitions
• Array definitions
• Reserved area definitions

Comments, blank lines, and Include statements can also be part of a block definition.

Concurrent access to multiple records of the same format

One image definition is required for each record to be accessed concurrently.

If you need concurrent access to multiple records of the same format, the image definition must be duplicated with a different name. This can be done easily by using an Include statement inside the image definition.

Image naming and reference conventions

Rules for image names

• An image name is a character string that consists of any number of letters, numbers, and some special characters. The name can have no embedded blanks, colons, or Model 204 reserved characters. Refer to Reserved words and characters for a complete list of reserved characters.
• An image cannot have the same name as a screen or menu.
• If Image, Menu, or Screen is an image name, it must be preceded by the keyword Image in Read Image and Prepare statements.

Rules for item names and array names

• Item and array names follow the same naming conventions as image names.
• Every image item name and array name must be unique within the block definition. An item name or array name can be reused in different blocks, screens, and menus.
• An item (or array) name and its image name cannot have a combined length exceeding 253.

Rule for reserved item names

The item name ReadLen is reserved by Model 204 to contain the length of the last record read into the block. This value can be obtained from the variable %imagename:ReadLen.

Do not duplicate names in the same block

Do not duplicate item, array, and image names within the same block.

References

To identify the item uniquely, all references outside the image definition must include the image name and item name, and they must be specified in this format:

%imagename:itemname

For example:

%INVENTORY:PART.NO

identifies the item PART.NO in the image INVENTORY.

Image and End Image statements

The Image statement starts the definition of an image block or of an additional image within the block. Each image can contain a description of the complete block, or it can redefine a portion of a preceding image in the block. An End Image statement completes the image block.

Syntax

The format of the Image block is:

[Declare] Image imagename [Namesave] [global | Common]
imageComponent
[imageComponent] ... [Image imagename2 [Namesave] [At {itemname | imagename | arrayname}]
imageComponent
[imageComponent] ... ] ...
End Image

where global is:

Global [Permanent | Temporary]
| [Permanent | Temporary] Global

Where:

• imagename is the name of the image. Every image name defined in a request must be unique. The image name specified in the Image statement is assigned to the image being defined; other SOUL statements in the request can subsequently refer to this name.
• Namesave is meaningful only for images used by certain $functions and OO methods: $Field_Image, $Field_ListI, and AppendFieldImages.
• Global specifies to store the image in GTBL. Global images have an implied scope of Common (see below).

  Note:

  • You must not specify the Global attribute for an image that has an image item defined with either of the following attributes:
    • Occurs Unknown
    • Len Unknown
  • Images that share a block must have the same scope. For multi-image blocks, you can specify only the first image as Global; you must not specify subsequent images in a multi-image block as Global. Specifying the first image as Global, declares the entire block of images as Global. The same behavior and restrictions apply to Common images in a block.

• Permanent can be used only with global images. Permanent global images persist across request boundaries; that is, they are maintained in GTBL even after a request has been terminated.
• Temporary can be used with only global images. Temporary global images are allocated in GTBL, but are deleted at request termination. For example, use a Temporary global image when you do not need to pass the image to another request; using Temporary global images eliminates the need to explicitly delete globals that do not need to persist.
• Common images, or images that are neither Common nor Global, are stored in FSCB.

  As described above for the Global option, you can specify only the first image in a multi-image block as Common, and you must not specify subsequent images in that block as Common.

  Common elements, as well as Declare and Common, are discussed in detail in Subroutines.

• imageComponent is any of the following (which are described in detail on this page):
  • Item definition
  • Array definition
  • Reserved area definition
  • Comment, blank line, or Include statement
  • Image definition (multiple-image block)
• The At clause is optional and specifies the starting location of a redefinition (that is, At is not suitable for the initial image in the block). If the At clause is omitted, the definition of this additional image starts at the beginning of the block. The location can be defined by one of the following options:
  • itemname is the name of an item in a previously defined image in this block.
  • imagename is the name of an image previously defined in this block.
  • arrayname is the name of an array in a previously defined image in this block.

  Note: You cannot use the At clause with a Global image, since you can only define the first image in a multi-image block as a global image.

End Image statement

The End Image statement must be the last statement in an image definition. End Image terminates the definition of all images that describe the same block.

The format of this statement is:

End Image

Examples of image definitions

Single image definition

An example of the definition of a single image follows:

IMAGE GENERAL.LEDGER.RECORD GL.RECORD.TYPE IS STRING LEN 1 GL.NUMBER IS STRING LEN 10 DP 3 GL.INV.TYPE IS STRING LEN 2 END IMAGE

Multiple image definition for the same block

The following example illustrates two images that define the same block. Each image completely defines the block, with the items named GL.RECORD.TYPE and AR.RECORD.TYPE both located at the first byte in the block.

IMAGE GENERAL.LEDGER.RECORD GL.RECORD.TYPE IS STRING LEN 1 GL.NUMBER IS STRING LEN 10 DP 3 GL.INV.TYPE IS STRING LEN 2 IMAGE ACCOUNTS.REC.RECORD AR.RECORD.TYPE IS STRING LEN 1 AR.ACCT.NO IS STRING LEN 6 AR.BALANCE IS PACKED DIGITS 9 DP 2 END IMAGE

Multiple image definition with shared items

When an image redefines part of another image, the At clause names an item or array in an image already defined in the record. Items preceding the named item or array in the block are combined with items defined following the Image statement to create the complete image description.

Therefore, the preceding example also could be defined in the following manner. The example illustrates two images that define the same block but share at least one item in common. In this example, the item RECORD.TYPE is shared by both images, and it can be referred to by prefixing the item name by either image name. The items GL.NUMBER and AR.ACCT.NO both begin at position 2 in the block.

IMAGE GENERAL.LEDGER.RECORD GL.RECORD.TYPE IS STRING LEN 1 GL.NUMBER IS STRING LEN 10 DP 3 GL.INV.TYPE IS STRING LEN 2 IMAGE ACCOUNTS.REC.RECORD AT GL.NUMBER AR.ACCT.NO IS STRING LEN 6 AR.BALANCE IS PACKED DIGITS 9 DP 2 END IMAGE

Special considerations for multiple-image blocks

When you define multiple-image blocks, take note whether the sum of the individual image items completely defines the block. Is there undefined space between the image items? If there are, you must initialize the space, otherwise you might get unexpected results, as illustrated in the following code.

Using uninitialized disk space

In the following multiple-image block, PART1, PART2, and PART3 define parts of the block without defining or initializing the space between them. When LINE is defined, which encompasses the entire block, the system assumes that the entire block has already been defined, because LINE begins at the same place as PART1.

R HDRCTL 0 BEGIN IMAGE A PART1 IS STRING LEN 10 PART2 IS STRING LEN 5 AT 16 PART3 IS STRING LEN 5 AT 26 LINE IS STRING LEN 30 AT PART1 END IMAGE PREPARE IMAGE A %A:PART1 = 'XXXXXXXXXX' %A:PART2 = 'YYYYY' %A:PART3 = 'ZZZZZ' SET HEADER 1 %A:LINE NP PRINT '%A:LINE = ' WITH %A:LINE PRINT '$C2X(%A:LINE) = ' WITH $C2X(%A:LINE) END

However, when output from the previous procedure is displayed, a stray numeral two appears twice in the header. This system read the string of zeros for the uninitialized space in the header (shown in the line that begins with $C2X) and automatically substituted the page number.

02.142 MAY 22 10.11.11 PAGE 2 XXXXXXXXXX 2YYYYY 2ZZZZZ %A:LINE = XXXXXXXXXX YYYYY ZZZZZ $C2X(%A:LINE) = E7E7E7E7E7E7E70000000000E8E8E8E8E80000000000E9E9E9E9E9

Using initialized disk space

Refining the previous code, the spaces between PART1, PART2, and PART3 are initialized by the intervening Skip statements:

R HDRCTL 0 BEGIN IMAGE A PART1 IS STRING LEN 10 SKIP 5 POSITIONS INITIAL BLANK PART2 IS STRING LEN 5 AT 16 SKIP 5 POSITIONS INITIAL BLANK PART3 IS STRING LEN 5 AT 26 LINE IS STRING LEN 30 AT PART1 END IMAGE PREPARE IMAGE A %A:PART1 = 'XXXXXXXXXX' %A:PART2 = 'YYYYY' %A:PART3 = 'ZZZZZ' SET HEADER 1 %A:LINE NP PRINT '%A:LINE = ' WITH %A:LINE PRINT '$C2X(%A:LINE) = ' WITH $C2X(%A:LINE) END

Now the output displays the expected results. The line that begins with $C2X has the hexadecimal representation of white space between the defined areas meaning that the space is initialized. The system prints only the white spaces:

02.142 MAY 22 10.12.26 PAGE 2 XXXXXXXXXX YYYYY ZZZZZ %A:LINE = XXXXXXXXXX YYYYY ZZZZZ $C2X(%A:LINE) = E7E7E7E7E7E7E74040404040E8E8E8E8E84040404040E9E9E9E9E9

Defining image items

You must define each item in an image that is referred to by the request. Use an item definition to describe the following attributes for an item:

• Data type
• Length
• Position
• Number of occurrences
• Editing options

Syntax

The general format of an item definition is:

itemname [Is [Type] type description]

Where:

• itemname is the name by which the item is referred to.
• Type is an optional keyword.
• type specifies the data type of the item. Data type options are:
  • String
  • Binary
  • Large Object data
  • Packed decimal
  • Zoned decimal
  • Floating point
  • Exponential notation
• description is the length, position, number of occurrences, and editing options specified for the item based on the data type.

The format used when defining an item for each data type is provided in the following table. In addition, an example of an image item definition appears in Item definition examples:

Term	Description
Numeric	All types except String are considered numeric.
Null	Binary zeros.
Omitted	The option is omitted from the item description and no default is specified.
String	A string of characters. A string must be enclosed in single quotes if it contains any of the following characters: blank, =, (, ), <, >, or ^.
Zero	Numeric zero of the correct format for numeric items. String and EFORMAT items are set to a single character zero.

Defining a string item

Syntax

Define string items with this syntax:

String {Len {n | Unknown} [Dp {k | *}] | To position} [Pad {Blank | character | Null}] [Strip | NoStrip] [Justify {Left | Right}] [Initial {Blank | string | Zero | Null}] [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}] [Occurs {n [Depending On {itemname | %variable}] | Unknown}]

Where:

• Len specifies the length either as 1-255 bytes or as Unknown, if the length is determined by the request and the Identify statement establishes the length.
• To specifies the last byte position of the item in the image as a number from 1 to 32767. The length (Len) or end (To) position of the item is required unless the length has been specified in a Default statement.
• Dp (optional) specifies either that the item has from 0 to 15 decimal places as specified by k, or that the number of decimal places is variable.
  • Dp k represents the number of places retained when a number is stored into an item and the number of places assumed to be present in data read from an external record.
  • If Dp * is specified, all decimal places in the item are retained. If this option is omitted, the default is zero. Do not use Dp, if the value to be moved to the item contains a decimal point.
• Pad (optional) defines the fill character. If a value is shorter than an item to which it is being moved, the pad character fills the remainder of the item. If Pad is omitted, a blank is assumed. Padding is done on the right end of left-justified items and on the left end of right-justified items.

  The pad character can be a single quoted character, a hexadecimal value expressed as X'hh', or a decimal number. The hexadecimal or decimal value can be from 0 to 255.

• Strip, the default, specifies to remove the pad characters, if an item value is extracted from an image. NoStrip specifies to keep the pad characters.
• Justify (optional) specifies whether a value is to be left- or right-justified when moved into an item by an assignment statement or when stripping on extraction. If Justify is omitted, the default is left-justified.
• Initial (optional) defines the value placed in the item by a Prepare statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If an Initial clause is omitted, Blank is the default initial value.

After and At clauses

• The After and At clauses are optional and mutually exclusive. Their function is as follows:

  An After clause defines the location of an item as immediately following the end of the specified item or array. This option is particularly useful when an item is redefined and the total length of the items in a redefinition is less than the length of the item.

  An At clause defines the location of the item in the image as adjacent to an item or array, or it redefines the space defined by a previously defined item. If the location is not adjacent in a forward direction to the previous item definition, a Skip is implied (see Default Skip statement).

  If position is used, the location is relative to the beginning of the image. The position option can have a value from 1 through 32767.

  An item or array named in the At clause cannot have a Depending On option.

  Consider the following restrictions when using an After or At clause:

  • Outside of an array definition, the After or At clause cannot name an item inside the array.
  • Within an array definition, the After or At clause cannot name an item outside of the array.
  • If neither After nor At is specified, the item abuts the end of the preceding item or the start of the image.

Occurs clause

• The Occurs clause (optional) specifies that there are multiple occurrences of the item. The Occurs clause options are as follows:
  • n specifies the maximum number of occurrences of the item for a depending array and the exact number of occurrences of the item for a fixed array. The value of n can be from 1 to 32767. Space for the maximum number of occurrences is reserved in a block created by a Prepare statement or when a block is read from a sequential file, VSAM file, or terminal.
  • The Depending On clause identifies the item or %variable that contains the current number of occurrences of this item. An item specified in this clause must be part of this image, cannot have length specified as Unknown, cannot be an array element, and cannot be positioned in the image following an item defined with Len Unknown or an array defined with Occurs Unknown.
  • Unknown specifies that the number of occurrences of the item is determined by the SOUL request and that the Identify statement establishes the number of occurrences.

Defining a binary item

Syntax

Define binary items with this syntax:

Binary {Len {n | Unknown} | Bits n | To position} [Bp n] [Signed | Unsigned] [Align] [Initial {Null | number | Blank | Zero}] [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}] [Occurs {n [Depending On {itemname | %variable}] | Unknown}]

Where:

• Len specifies the length as 1-4 bytes, or as Unknown if the length is determined by the request and the Identify statement establishes the length.
• Bits specifies the length as 8, 16, 24, or 32 bits.
• To specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (To) position of the item is required unless provided in a Default statement.
• Bp (optional) specifies the number of binary places retained when a number is stored in the item and the number of places assumed present in data read from an external record. The number of places can range from zero to the number of bits defined by the length option, the maximum is 31 bits. If Bp is omitted, the default value is zero.
• Signed, optional and the default, specifies that a negative number can be stored in the item in two's complement form. Unsigned, optional, specifies that the item is always positive and that the leftmost bit is part of the number.

  Note: If a negative number is read into an Unsigned Binary item, Model 204 uses the absolute value of that number.

• Align, optional, specifies that the item is aligned as follows:
  • Binary Len 2 on a halfword boundary
  • Binary Len 4 on a fullword boundary

  The Align option is ignored for 1- and 3-byte Binary items.

  The item is aligned by inserting a Skip statement preceding the item so that the item's location is on the correct boundary. In arrays, a Skip is inserted at the end of each occurrence of the array and of any parent array to make the length of each occurrence a multiple of the largest aligned item in the array.

  The Alignoption cannot be specified for an item:

  • When length is defined as Unknown.
  • When location is unknown during compilation because a previously defined item specified Len Unknown or Occurs Unknown.
  • Containing an At clause that specifies a location that is not already aligned on the proper storage boundary.
• Initial (optional) defines the value placed in the item by a Prepare statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, Null is the default initial value.
• The optional After and At clauses are mutually exclusive; they define the location of the item in the image. For a complete discussion, see Defining a string item.
• The optional Occurs clause specifies that there are multiple occurrences of the item. For a complete discussion, see Defining a string item.

Defining a packed decimal item

Syntax

Define packed decimal items with this syntax:

Packed {Len {n | Unknown} | Digits n | To position} [Dp n] [Signed | Unsigned] [Initial {Zero | number | Blank | Null}] [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}] [Occurs {n [Depending On {itemname | %variable}] | Unknown}]

Where:

• Len specifies the length as 1-8 bytes or as Unknown if the length is determined by the request and the Identify statement establishes the length.
• Digits specifies the length as 1-15 decimal digits.
• To specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a Default statement.
• Dp (optional) and specifies the number of decimal places to be retained when a number is stored in this item, that is, the number of places assumed present in data read from an external record. The value of n can range from 0 to 15. If this option is omitted, the default is zero.
• Signed, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal C for a positive number and D for a negative number.
• Unsigned (optional) specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F.
• Initial (optional) defines the value placed in the item by a Prepare statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is a packed zero.
• The mutually exclusive and optional After and At clauses define the location of the item in the image. For a complete discussion, see Defining a string item.
• The optional Occurs clause specifies that there are multiple occurrences of the item. For a complete discussion, see Defining a string item.

Defining a zoned decimal item

Syntax

Define zoned decimal items with this syntax:

Zoned {Len {n | Unknown} | Digits n | To position} [Dp n] [Signed | Unsigned] [Initial {Zero | number | Blank | Null}] [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}] [Occurs {n [Depending On {itemname | %variable}] | Unknown}]

Where:

• Len specifies the length as 1-15 bytes, or as Unknown if the length is determined by the request and the Identify statement establishes the length.
• Digits specifies the length as 1-15 decimal digits.
• To specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (To) position of the item is required unless provided in a Default statement.
• Dp, optional, specifies the number of decimal places to be retained when a number is stored in this item, that is, the number of places assumed present in data read from an external record. The value of n can range from 0 to 15. If this option is omitted, the default is zero.
• Signed, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal C for a positive number, and it is D for a negative number.
• Unsigned, optional, specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F.
• Initial, optional, defines the value placed in the item by a Prepare statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is zoned decimal zeros.
• The mutually exclusive and optional After and At clauses define the location of the item in the image. For a complete discussion, see Defining a string item.
• The optional Occurs clause specifies that there are multiple occurrences of the item. For a complete discussion, see Defining a string item.

Defining a floating point item

Syntax

Float {Len {n | Unknown} To position [Initial {Zero | number | Blank | Null}] [Align] [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}] [Occurs {n [Depending On {itemname | %variable}] | Unknown}]

Where:

• Len specifies the length as 4, 8, or 16 bytes, or as Unknown if the length is determined by the request and the Identify statement establishes the length.

  Although you can move 16-byte floating-point values between data sets and files, intermediate results and %variables inside SOUL are 8 bytes long.

  Arithmetic manipulations and data conversions retain only 15 significant decimal digits in 8 bytes.

• To specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (To) position of the item is required unless provided in a Default statement.
• Initial, optional, defines the value placed in the item by a Prepare statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is a floating point zero.
• Align, optional, specifies that the item is aligned as follows:
  • Float Len 4 on a fullword boundary
  • Float Len 8 on a doubleword boundary
  • Float Len 16 on a doubleword boundary

  The item is aligned by inserting a Skip statement preceding the item so that the item's location is on the correct boundary. In arrays, a Skip statement is inserted at the end of each occurrence of the array and any parent array to make the length of each occurrence a multiple of the largest aligned item in the array.

  The Align option cannot be specified for an item:

  • When length is defined as Unknown.
  • When location is unknown during compilation because a previously defined item specified Len Unknown or Occurs Unknown.
  • Containing an At clause that specifies a location that is not already aligned on the proper storage boundary.
• The optional After and At clauses are mutually exclusive; they define the location of the item in the image. For a complete discussion, see Defining a string item.
• The optional Occurs clause specifies that there are multiple occurrences of the item. For a complete discussion, see Defining a string item.

Defining an exponential notation item

Syntax

Define exponential notation items with this syntax:

Eformat {Len {n | Unknown} | To position} [Pad {Blank | character | Null}] [Strip | NoStrip] [Justify {Left | Right}] [Initial {Blank | string | Zero | Null}] [Digits n] [Dp n] [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}] [Occurs {n [Depending On {itemname | %variable}] | Unknown}]

Where:

• Len specifies the length either as 1-255 bytes, or as Unknown if the length is determined by the request and the Identify statement establishes the length.
• To specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (To) position of the item is required unless provided in a Default statement.
• Pad, optional, defines the fill character. If a value is shorter than an item to which it is being moved, the pad character fills the remainder of the item. Padding is done on the right end of items that are left-justified and on the left end for items that are right-justified. The pad character can be a single quoted character, a hexadecimal value expressed as X'hh', or a decimal number from 1 to 255.
• Strip, the default, specifies that the pad character is removed if an item value is extracted from an image. NoStrip specifies to keep the pad characters.
• Justify, optional, specifies whether a value is to be left- or right-justified when moved into an item by an assignment statement. The default behavior is left-justified.
• Initial, optional, defines the value placed in the item by a Prepare statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. A single character zero is the default value.
• Digits specifies the maximum number of significant digits — the total number of digits to the left and right of the decimal point. The value of n can be a number from 1 to 15.
• Dp specifies the number of digits to be placed to the right of the decimal point when a value is moved into the item.
• The mutually exclusive and optional After and At clauses define the location of the item in the image. See Defining a string item, for a complete discussion.
• The optional Occurs clause specifies that there are multiple occurrences of the item. See Defining a string item for a complete discussion.

Item definition examples

An image containing various item types

IMAGE GENERAL.LEDGER.RECORD GL.RECORD.TYPE IS STRING LEN 1 GL.NUMBER IS ZONED LEN 10 DP 0 GL.INV.TYPE IS STRING LEN 2 GL.DEPRECIATION.CODE IS STRING LEN 2 GL.BOOK.VALUE IS PACKED DIGITS 9 DP 2 GL.YEARS.REMAINING IS BINARY LEN 4 GL.QUANTITY.ON.HAND IS BINARY LEN 4 GL.ITEM.SIZE IS FLOAT LEN 4 END IMAGE

Using the At and After clauses

IMAGE PRINT.DATA PRINT.LINE1 IS STRING LEN 133 DP * PRINT.CC IS STRING LEN 1 AT PRINT.LINE1 PRINT.ITEM1 IS STRING LEN 8 SKIP 2 POSITIONS PRINT.ITEM2 IS STRING LEN 7 SKIP 2 POSITIONS PRINT.ITEM3 IS STRING LEN 8 SKIP 2 POSITIONS PRINT.ITEM4 IS STRING LEN 6 PRINT.LINE2 IS STRING LEN 133 DP * AFTER PRINT.LINE1 END IMAGE

In the preceding example, PRINT.LINE2 is placed adjacent to the end of PRINT.LINE1. Without the After clause, an At clause would be required to specify the numeric position of PRINT.LINE2 in the image.

Defining arrays

An array contains multiple occurrences of a single item or a group of items.

Array definition statements

When an array is a single item, the array can be defined by using the Occurs clause on the item definition or an Array statement.

When an array contains more than one item, the array is defined by using an Array statement, and it is followed by definitions of the items that compose each element of the array.

None of the items in an array or subordinate array can specify Len Unknown or Occurs Unknown.

Types of arrays

The format of the Array statement depends on which of the following types of arrays is being defined:

For type of array...	The number of occurrences in the array is...
Fixed occurrence	Constant.
Depending	Constant as defined in the image, but a record that is read from a sequential file, VSAM file, or terminal or is written to a sequential file or terminal can contain a smaller number of occurrences.
Unknown	Not known. The maximum number of occurrences must be specified during evaluation by using the Identify statement.

Array and End Array statements

You define an array with an Array statement. The definitions of items and subordinate arrays follow the Array statement.

You specify the end of the array with an End Array statement. End Array ends the definition of the array defined by the preceding Array statement. In addition, an Image or End Image statement ends all preceding Array definitions.

Defining a fixed occurrence array

A fixed occurrence array has a specified number of occurrences. Each external record read from a sequential file, VSAM file, or terminal or written to a sequential file or terminal is assumed to contain that number of occurrences.

Syntax

The format of the Array statement used to define a fixed occurrence array is:

Array [arrayname] Occurs n [After {itemname | arrayname} | At {position | itemname | imagname1 | arrayname}

Where:

• arrayname (optional) names the array. An array must be named if it is specified in the At clause of an image definition or in the After or At clauses in an item definition.
• n is the number of occurrences of the items in the array, which can range from 1 to 32767.
• After and At clauses are mutually exclusive and optionally specify the location of the array in the image. See Defining a string item for detailed information.

Example

The following example of an image contains a fixed occurrence array. In this example, each element of the SALES.MONTHLY array contains the item SALES.TOTAL and five occurrences of the item SALES.BY.MODEL.

IMAGE SALES ARRAY SALES.MONTHLY OCCURS 12 SALES.TOTAL IS PACKED DIGITS 9 DP 2 SALES.BY.MODEL IS PACKED DIGITS 9 DP 2 - OCCURS 5 END ARRAY END IMAGE

The same image could be written as:

IMAGE SALES ARRAY SALES.MONTHLY OCCURS 12 SALES.TOTAL IS PACKED DIGITS 9 DP 2 ARRAY OCCURS 5 SALES.BY.MODEL IS PACKED DIGITS 9 DP 2 END ARRAY END ARRAY END IMAGE

Defining a depending array

A depending array has a fixed number of occurrences in the image, but a smaller number of occurrences can be found in records read from a sequential file, VSAM file, or terminal or records written to a sequential file or terminal.

Depending variable

A depending variable is used to specify the actual number of occurrences that exist in the record.

The depending variable is used in this manner:

• When a record is read from a sequential file, VSAM file, or terminal into an image, the record is assumed to contain only the number of occurrences specified by the value in the depending variable. The depending variable must have a value from zero to the maximum number of occurrences in the array. The occurrences specified in the variable are moved to the image and any remaining occurrences are initialized. When an image is created by a Prepare Image statement, space in the image is allocated for the maximum number of occurrences.
• When a record is written from an image to a sequential file or terminal, the record is assumed to contain only the number of occurrences specified by the value in the depending variable. Therefore, the record is written with all unfilled occurrences removed.

If a subordinate array has a depending variable, the value of that variable applies to all occurrences of the outer array.

Restrictions

A depending array cannot be redefined in the current image or in any other image in the block. In addition, a depending array and the After or At clause are mutually exclusive.

Syntax

The form of the Array statement used for defining a depending array is:

Array [arrayname] Occurs n Depending On {itemname | %variable}

Where:

• arrayname, optional, names the array. An array must be named if it is specified in the At clause of an image definition or in the After or At clauses of an item definition.
• n is the number of occurrences of the items in the array, which can range from 1 to 32767.
• The Depending On clause names a previously defined %variable or item within the image that contains the actual number of occurrences in an input record. An item used as the depending variable cannot:
  • Be an array element
  • Vary in length, that is, be defined with Len Unknown
  • Follow any varying length item or array in the image.

Example

The following example of an image contains an array with a depending variable is shown below. In this example, SALES.MODELS contains 15 occurrences of the item SALES.MODEL.NO. Therefore, the external record can contain from 0 to 15 occurrences.

IMAGE SALES SALES.MODELS IS BINARY LEN 2 ARRAY OCCURS 15 DEPENDING ON SALES.MODELS SALES.MODEL.NO IS PACKED DIGITS 9 INITIAL 0 END ARRAY END IMAGE

If a record is read into the previous image, the number of items defined by the value of the item SALES.MODELS are moved from the record into the array. Any occurrences of SALES.MODEL.NO not filled in the array from the record are initialized to zero. Before a record is written from the SALES image to a sequential file or terminal, the number of items defined by the value of the item SALES.MODELS are moved from the array into the record. Any unused occurrences are not present in the record written to the sequential file or terminal.

Defining an unknown array

An array must be defined as unknown when you cannot determine the maximum number of occurrences until after the data moves into the image. The number of occurrences in the array is specified as Unknown. During evaluation, the Identify statement is used to specify the number of occurrences in the array before any item in the array is referred to.

Syntax

The format of the Array statement used for defining an unknown array is:

Array [arrayname] Occurs Unknown [After {itemname | arrayname} | At {position | itemname | imaginename1 | arrayname}]

Where:

• arrayname is required and names the array. This name is used to identify the array in Identify statements that specify the number of occurrences during evaluation.
• The After and At clauses are mutually exclusive and optionally specify the location of the array in the image. See Defining a string item for detailed information.

Example

This example illustrates the use of unknown arrays. In this example, the number of occurrences of the array TRANSACTION is contained in the item TRANS.COUNT. Before the items TRANS.NO, TRANS.AMT, or TRANS.CUST can be referred to, the Identify statement is executed to set the number of occurrences.

TRANS.COUNT IS BINARY LEN 4 ARRAY TRANSACTION OCCURS UNKNOWN TRANS.NO IS PACKED LEN 5 TRANS.AMT IS PACKED LEN 7 DP 2 TRANS.CUST IS STRING LEN 10 END ARRAY

Referring to array elements

Individual items within an array are identified by subscripts. A subscript is enclosed in parentheses and can be any expression that evaluates to a number from 1 to the maximum size of the array.

Nested arrays

If arrays are nested, subscripts are required for each nesting level and are separated by commas. The outermost array is the first subscript.

Example

In this example, the fifth student in the second course would be referred to as COURSE.STUDENT(2,5).

IMAGE COURSE.DATA ARRAY OCCURS 20 COURSE.NUMBER IS BINARY LEN 4 COURSE.NAME IS STRING LEN 25 COURSE.INSTRUCTOR IS STRING LEN 20 COURSE.STUDENT IS STRING LEN 20 OCCURS 30 END ARRAY END IMAGE

Initialization of array values

Model 204 lets you specify multiple value assignments into array dimensions within a single User Language assignment statement by adding an asterisk (*) as the subscript value. Using the asterisk is valid for percent variable arrays and image arrays.

Example 1

The following statement sets all elements in all dimensions to 0:

%ARRAY.ITEM (*,*,*) = 0

Example 2

If an array is defined as occurs 3, occurs 4, occurs 2, %ARRAY.ITEM(*,2,*) = 9 is equivalent to the following:

%ARRAY.ITEM(1,2,1) = 9 %ARRAY.ITEM(1,2,2) = 9 %ARRAY.ITEM(2,2,1) = 9 %ARRAY.ITEM(2,2,2) = 9 %ARRAY.ITEM(3,2,1) = 9 %ARRAY.ITEM(3,2,2) = 9

Example 3

The following example prints AAA and 100:

BEGIN IMAGE TEST ARRAY OCCURS 5 PART1 IS BINARY LEN 2 PART2 IS FLOAT LEN 8 PART3 IS STRING LEN 3 OCCURS 4 PART4 IS FLOAT LEN 8 OCCURS 2 END ARRAY END IMAGE PREPARE IMAGE TEST %TEST:PART3(3,*) = 'AAA' %TEST:PART4(*,2) = 100 PRINT %TEST:PART3(3,4) PRINT %TEST:PART4(2,2) END

Example 4

The asterisk is not valid on the right side of a SOUL assignment statement. The following statement is invalid and causes a compilation error:

%X = %ARRAY.ITEM(*,*,*)

Using Large Object fields with a very large array

If you have a very large array that is densely populated and not a preallocated field, you may improve performance by storing this array of data in a Large Object field.

When an array of data is used as a field that is not preallocated, then each field reference includes the overhead of walking through the record to find that fieldname(fieldoccurrence) value.

With a Large Object field, you can directly address each item using the offset,length syntax available for Large Object fields.

There is one Table B access to retrieve the Large Object descriptor, and one Table E access to read the page that your data resides on, no matter how far into the object the data resides.

There may be a substantial CPU reduction for applications that reference large arrays as Large Object data instead of holding each array entry in a field occurrence.

Cautionary usage note: Disk space utilization: Each Large Object field requires the total Large Object length rounded up to the next 6184 bytes of space.This is because Large Object data is a collection of Table E pages; you cannot allocate just part of a page.

Defining reserved space

The format of the entire block does not have to be specified in an image definition. When items are not contiguous, space must be reserved to correctly position the items.

Space is reserved automatically by an At clause that places an item beyond the end of the last defined item.

Skip statement

Space is reserved explicitly by using the Skip statement. The space reserved by a Skip statement can be initialized by a Prepare statement but cannot be accessed.

Syntax

The format of the Skip statement for reserving space is:

[itemname Is] Skip n Position[s]
[Initial {Null | character | Blank}]

Where:

• The itemname Is clause (optional) names a reserved area that can be referred to by an After or At clause.
• n is the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.
• The Initial clause indicates the character with which the area is filled by Prepare and Identify statements. Options are as follows:
  • character — a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as X'hh'
  • Blank — white spaces
  • Null — binary zeros

  If the Initial clause is omitted, Null is the default.

Example

This sample Skip statement reserves two bytes before the next image item:

SKIP 2 POSITIONS

Default Type and Default Skip statements

You can provide default values for image item options to eliminate repetition of these options on each item definition, using:

• Default Type
• Default Skip

Default Type statement

The Default Type statement lets you set default option values for each item type. The options specified on a Default Type statement for an item type are applied to each item of that type defined between the default statement and the next default statement of the same item type.

Syntax

The format of the Default Type statement is:

Default [Type] type options

Where:

• The optional Type keyword specifies a default data type for any item definition that does not explicitly define the data type. Without the Type keyword, the statement defines the default option values for an item type without defining the default item type.
• type specifies the data type of the item. Valid values are String, Binary, Float, Packed, Zoned, or EFormat.
• options specifies any of the options that are valid for the item type except for the To, After, At, and Occurs clauses.

Default Skip statement

The Default Skip statement specifies the default length or initial value for a Skip statement or an implied skip. It can appear anywhere in an image definition and remains in effect until the next Default Skip statement.

Syntax

The format of the Default Skip statement is:

Default Skip n Position[s] [Initial {Null | 'character' | Blank}]

Where:

• n is a positive integer that specifies the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.
• The Initial clause indicates the fill character for Prepare and Identify statements. Options are as follows:
  • Null — binary zeros
  • character — a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as X'hh'
  • Blank — white space

  If the Initial clause is omitted, Null is the default.

Example of Default statements

The following examples show how an image can be described without and then with Default statements.

Without Default statements

IMAGE SALES SALES.YEAR.TOTAL IS PACKED DIGITS 7 DP 2 SALES.MONTH.TOTAL IS PACKED DIGITS 7 DP 2 SALES.REP.NO IS PACKED DIGITS 5 SALES.REP.NAME IS STRING LEN 20 SALES.REP.ADDRESS.1 IS STRING LEN 20 SALES.REP.ADDRESS.2 IS STRING LEN 20 END IMAGE

With Default statements

IMAGE SALES DEFAULT TYPE STRING LEN 20 DEFAULT PACKED DIGITS 7 DP 2 * THE FOLLOWING TWO ITEMS DEFAULT TO DIGITS 7 DP 2 SALES.YEAR.TOTAL IS PACKED SALES.MONTH.TOTAL IS PACKED * DP 0 IS NECESSARY ON THE NEXT LINE IN ORDER TO AVOID * THE DEFAULT OF 2 SALES.REP.NO IS PACKED DIGITS 5 DP 0 * THE FOLLOWING 3 ITEMS DEFAULT TO STRING LEN 20 SALES.REP.NAME SALES.REP.ADDRESS.1 SALES.REP.ADDRESS.2 END IMAGE

Processing images

Once a block is defined, you can use the following statements to process external records and to manipulate a block of storage.

Statement	Action undertaken
Close	Closes a sequential file, VSAM file, or terminal opened by the request.
Identify	Defines an active image and establishes the length for items or array occurrences defined as Unknown.
Open	Opens a sequential file, VSAM file, or terminal for processing.
Position	Specifies the next record to be read sequentially in a VSAM KSDS file.
Prepare	Initializes an image.
Read Image	Reads a record from a sequential file, VSAM file, or terminal.
Release Position	Terminates the browse operation established by a Position statement.
Write Image	Writes a record to a sequential file or to a terminal.

Key field for VSAM files

When the VSAM key is not in character format, special handling is required to supply the key in the format required by VSAM. If the key is supplied as a %variable or image item that has a numeric type, the Read Image and Position statements attempt to convert the numeric value to string.

The suggested technique to resolve this problem is to define the image of the record with the key field defined in the format expected by VSAM and redefined as a string of the same length. The key value is moved to the key item and the string item name is provided in the Read or Position statement.

An example of this technique for a VSAM file that has a 4-byte binary key is illustrated below:

IMAGE VSAM.REC KEY IS BINARY LEN 4 KEY.STR IS STRING LEN 4 AT KEY . (additional items) . END IMAGE OPEN DATASET VSAMFILE IF $Status NE 0 THEN PRINT $Errmsg STOP END IF %KEYVAL = $READ('KEY VALUE = ') PREPARE VSAM.REC %VSAM.REC:KEY = %KEYVAL READ IMAGE VSAM.REC FROM VSAMFILE KEY EQ %VSAM.REC:KEY.STR . . .

Close statement

The Close statement lets the request close a sequential file, VSAM file, or a terminal opened by the request.

Syntax

The format of the Close statement for external I/O is:

Close
{Dataset | External} {ext-filename | %variable}
| [External] Terminal

Where:

• You must specify the Dataset, External, or Terminal keyword.
• Dataset specifies that the entity to be closed is a non-Model 204 file, that is, a sequential or VSAM file.
• External specifies that the entity to be closed is a non-Model 204 file, that is, a sequential or VSAM file, or a terminal.
• ext-filename specifies the name of the sequential or VSAM file to close, that is, the name used in the Open statement. Also, a %variable can provide the file name.
• Terminal specifies that the terminal currently opened by the Open statement should be closed. Also, a %variable can supply the word Terminal.

Closing a Model 204 file

The Close statement can be used only for closing external files or terminals. To close a Model 204 file, you may use the $Close function within a SOUL request, or the CLOSE command outside a request.

Identify statement

The Identify statement establishes:

• Active image, if multiple images define the same block.
• Length of items that were defined as Unknown.
• Number of occurrences for arrays that were defined as Unknown.

Syntax

The complete syntax for the Identify statement follows. The form of the Identify statement used to perform each of these activities is then discussed in detail.

Identify
{ [Image] imagename
| %imagename:itemname Len {n | %variable}
| {%imagename:arrayname | %imagename:itemname} Occurs {n | %variable} }

Where:

• imagename refers to an image that was previously described in an image definition.
• %imagename:itemname is an item that was defined with Len Unknown or Occurs Unknown.
• The Len clause specifies the length in bytes of the item or a %variable that contains the length. The length cannot exceed 255 bytes.
• %imagename:arrayname is an array that was defined with Occurs Unknown.
• The Occurs clause specifies the number of occurrences of the item or a %variable that contains the number. The number of occurrences cannot exceed 32767.

Establishing an active image

Use the following form of the Identify statement to switch the active image to the named image, when multiple images define the same block:

Identify [Image] imagename

The Identify statement also initializes the items, if any, that were not initialized by a previous Read Image or Prepare statement.

Note: Use the Identify statement instead of a Prepare statement for requests in which you want to maintain data passed in an image.

Use with global images

When used with global images, the Identify Image statement can cause request termination due to either of these:

• Definition mismatches. See Consistency checks performed for a description.
• Insufficient space in GTBL.

The Identify Image statement does not refresh a global image, if a copy of that image is already in GTBL. The Identify Image statement simply makes the specified image active. See Images and screen processing for a diagram showing the structure of GTBL followed by a discussion of performance considerations with respect to the definition of global objects.

Establishing lengths for Unknown items

Use the following form of the Identify statement to set the length for items defined with Len Unknown:

Identify %imaginename:itemname Len {n | %variable}

The location of an item is established when the length of every preceding variable length item and array is established. The length cannot be changed after it is defined by an Identify statement. If you must enlarge an array after the length is established, copy the image (using assignment statements) to another image where the array is larger.

Establishing occurrences for Unknown arrays

Use the following form of the Identify statement to set the number of occurrences for arrays or items defined with Occurs Unknown:

Identify {%imagename:arrayname | %imagename:itemname} Occurs {n | %variable}

You cannot change the number of occurrences after they are defined by an Identify statement. If you issue an Identify statement for an item whose length was previously set by an Identify statement, the request is cancelled.

You must issue a Prepare statement before another Identify statement can be issued on the same item. If you need to enlarge an array after the number of occurrences is established, you must copy the image (using assignment) to another image where the array is larger.

Modify Buffer statement

Function

Manages the Universal Buffer size and can also keep messages or overwrite them with a fill character.

Syntax

Modify Buffer [Size=n | %variable [Preserve | Nopreserve]] [Fill [X'nn' | C'x'] | CLEAR]

Where:

• Buffer (formerly and still accepted as MQ_BUFFER) specifies the Universal Buffer area.
• Size specifies the number of bytes allocated for the Buffer area. If the value of the Size option enlarges or shrinks the current buffer, the buffer contents are overwritten.
• Preserve specifies to retain the buffer contents. If a storage allocation error occurs, the value of 8 is set in the $Status return code (which is the standard WebSphere MQ value for this error).

  If the data was truncated when the buffer was shrunk, then the value of 14 for data truncation is set in $Status, although the operation succeeds.

• Clear option, the default, specifies to overwrite the buffer with X'00'.
• Fill option specifies a fill-character to use; for example, X'40' fills with blanks. The Fill option can also be a decimal number and/or the equals sign (=), or it can be an alpha character (C) and/or the equals sign. If a value is not specified after the keyword Fill, the default value is the Clear option.

  If the Fill or Clear option is specified, the behavior of the Modify Buffer statement depends on what other options are used:

  If...	Then...
  Fill/Clear, Size, and NoPreserve are specified, or Fill is specified without Size	Entire buffer is filled with the fill character.
  Fill/Clear, Size, and Preserve are specified	Fill character is used to fill the new portion of the buffer after the preserved data only if the buffer size is increased.

Usage

The Modify Buffer statement requires that you specify at least one option.

When you overwrite the contents of the Buffer area, the value of $Buffer Used is set to zero, and the value of $Buffer Position is set to one.

If you exceed the 2-gigabyte limit on the size of Buffer, $Status returns a value of 34. A negative number or a number less than UBUFSZ is changed to UBUFSZ.

Open statement

The Open statement can be used to open a sequential file, VSAM file, or terminal for processing.

DEFINE DATASET required

Before a VSAM file or a DOS sequential file can be opened, it must previously have been defined using the DEFINE DATASET command.

Syntax

The format of the Open statement for external I/O is:

Open { [Dataset | External] {ext-filename | %variable} | [External] {Terminal | %variable} } For {Input [Output] | Output [Input] | InOut} [Password {value | %variable}]

Where:

• Either the Dataset or External keyword must be specified to open a sequential (non-Model 204) file. Dataset and External should not be specified for opening Model 204 files.
• ext-filename specifies the name of external file (that is, the sequential or VSAM file) to be opened. The external file name is the name specified in the DEFINE DATASET command or, for sequential files, the OS DDNAME or CMS FILEDEF. The external file name can be provided in a %variable.
• Terminal specifies that the entity to be opened is a terminal. The word Terminal can be provided in a %variable.
• The required For clause specifies the type of I/O processing that is performed on the opened external file or terminal. An external file or terminal must be opened for at least Input to be read into an Image and opened for at least Output to write data from an Image.

  The Input Output, Output Input, and InOut combination options are valid only for the Terminal keyword.

• The Password clause is required for only password protected VSAM data sets. The clause generates an error when used with an Open Terminal statement, but is ignored in all other cases.

  With the Password clause, the password can be specified directly or can be provided as the value of a %variable. Password validation is performed during evaluation and is not checked during compilation.

Usage notes

Open statement in remote context

This form of the Open statement is not supported in remote context. Using the At keyword with any of the keywords Dataset, External, or Terminal generates the following error message, which is not displayed on the terminal, but can be retrieved with the $Errmsg function:

M204.1497: Remote specification conflicts with open type

Multiple Opens of external data sets

An attempt to open an already open external data set results in request cancellation with the following error message:

M204.2153 Dataset name is already open

Clearing messages

An Open statement resets the messages accessed by the $Fsterr and $Errmsg functions. You may also clear the messages using the $ErrClr function.

See also

• An Open statement without the Dataset or External keyword is used to open a Model 204 file or group, similar to the OPEN command (for example, the OPEN FILE command).
• The Dataset class can also be used to access external data sets.

Position statement

The Position statement specifies the next record to be read sequentially in a VSAM KSDS file. An established position is used by the Read next statement to locate the next record to be returned. A new position can be established at any time by executing another Position statement.

This Position statement is not to be confused with the Position statement used to recall a position in a found set or list which has been saved using the Remember option during For loop processing. See Position statement.

Syntax

The format of the Position statement is:

Position {ext-filename | %variable} At Key operator {value | %variable}

Where:

• ext-filename is the name of the VSAM file specified in the Open statement. The name can be provided as the value of a %variable.

  If ext-filename is provided as a literal, it cannot be the name of a found set or list.

• operator specifies that the key of the record to be retrieved must be equal to or greater than or equal to the specified value. Valid operators are: =, >=, EQ, or GE.
• value specifies the key at or beyond which the file is positioned for subsequent reads. The key can be provided as the value of a %variable.

  If value is a null string, a key of binary zeros is substituted. The first record in the file is returned if the operator is >= or GE. If the operator is = or EQ, a record is found only if it has a key of all binary zeros.

  If the length of value is less than the length of the VSAM key, the key is treated as generic. A generic key search is satisfied when the value matches the same number of characters at the beginning of the VSAM key. The portion of the VSAM key that is longer than the value is ignored in the comparison.

  If the VSAM key is not a character string, special handling is required. For information on how to specify the key when the key is not a string, refer to Key field for VSAM files.

Prepare statement

The Prepare statement initializes an image and makes it the active image. This is required when image items are accessed prior to reading an external record into the image. Prepare initializes the block associated with the image with the values specified in the Initial clauses of the item definitions or Default statements.

Previous identifications of lengths of items defined as length Unknown or number of occurrences of arrays defined with Occurs Unknown are lost. The Identify statement must be executed again to establish length or number of occurrences.

Syntax

The format of the Prepare statement is:

Prepare [Image] imagename

where imagename refers to an image that was previously described in an image definition. The keyword Image is required if imagename is Image, Menu, or Screen.

Use with global images

The Prepare Image statement, when used with global images, can cause request termination due to either:

• Definition mismatches (see Consistency checks performed for a description for global images)
• Insufficient space in GTBL.

Read Image statement

The Read Image statement reads a record from a sequential or VSAM file or terminal into the image and sets the image as the active image. Or, the Read Image statement reads the contents of the Universal Buffer.

Syntax

Read [Image] imagename From {ext-filename | Terminal | %variable} [Prompt {'text' | %variable}] [Next | Key operator {value | %variable}]

Read [Image] imagename From Buffer [Position={%pvariable | n}] [Maxlen={%lvariable | n}]

Where:

• imagename is an image that was previously described in an image definition. The keyword Image is required if imagename is Image, Menu, or Screen. imagename also specifies a message to read in the Universal Buffer area.
• The From clause determines which use of the Read Image statement to employ:
  • Reading Large Object data from the Universal Buffer
  • Reading from a sequential file or the terminal
• Buffer (formerly, and still accepted as Mq_Buffer) specifies the Universal Buffer area.
• Position must be in the range 1-16,777,216. If not, the operation returns $Status=10 and $StatusD=20 return codes. %pvariable or n specifies where in the buffer to begin reading.

  If Position=%pvariable is specified and %pvariable is greater than $Buffer_Used, the operation returns $Status=10 and $StatusD=20.

  The starting position in the buffer is determined by Position=%pvar, if that was specified; $Buffer_Position, otherwise.

  The ending position in the buffer is determined by the lowest of starting position, plus %lvariable, if Maxlen=%lvariable was specified as the value of $Buffer_Used.

• Maxlen=%lvariable specifies the maximum number of bytes to copy into the image. The actual number copied might be less than that, either because the number of bytes available in the Universal Buffer (from the starting position) is less, or because the size of the image is less.

  Maxlen must be in the range 1-32,767. If not, the operation returns $Status=10 and $StatusD=19.

• ext-filename specifies that records are read from a previously opened sequential or VSAM file. The name of the file can be provided as the value of a %variable.
• Terminal specifies that records are read from the terminal. The keyword Terminal can be provided as the value of a %variable.
• The optional Prompt clause is used with only the Terminal option. It specifies to display a prompt sign before the read is performed. Prompting is especially useful for synchronizing communication between the SOUL request and Host Language program.

  The Prompt string can be as many as 255 characters. The string can be provided as a string type %variable.

• The Next option reads the next record in the file. Next is the default, if the Key clause is omitted. A Read Image statement with the Next option can be executed only following an Open, Position, or Read Next statement.
• The Key clause identifies the record to read. The Key clause is valid only for VSAM files and the value is converted to a string. A Read Image statement with the Key clause automatically performs a Release Position.

  Key clause options are operator and value:

  • operator specifies that the key of the record to be retrieved must be equal to or greater than or equal to the specified value. Valid operators are: =, >=, Eq, or Ge.
  • value is the key that locates the record. It can be supplied in a %variable.

    If the value is a null string, a key of binary zeros is substituted. The first record in the file is returned, if the operator is >= or Ge. If the operator is = or Eq, a record is found only ifit has a key of all binary zeros. If the length of the value is less than the length of the VSAM key, the key is treated as generic. A generic key search is satisfied when the value matches the same number of characters at the beginning of the VSAM key. The portion of the VSAM key that is longer than the value is ignored in the comparison.

  If the VSAM key is not a character string, special handling is required. For information on how to specify the key when the key is not a string, refer to Key field for VSAM files.

Usage

This statement is valid only if the file or terminal from which the record is read is currently open for Input, Input Output, or InOut. Read Image processing reads data until the Universal Buffer is exhausted, or the image is filled.

The part of the message selected is copied from the Universal Buffer to the image:

• Contents of the Universal Buffer are unchanged.
• $Buffer_Used is unchanged.
• $Buffer_Position is set to the byte after the last byte copied.
• No error indication is given, if the image is not big enough to hold the data.

Buffer area positioning

If Position is specified:

• Numeric value, expressed as either a constant or variable, indicates where in the buffer to begin reading; the count starts from 1.
• Beyond the end of the data, then the image is unchanged; ReadLen is set to 0.
• If the value is nonnumeric, less than one, or beyond the end of the data, then the statement fails with a nonzero $Status value.

If the Position option is not specified:

• Data is extracted from the buffer at the point where the last READ left off, or from the beginning of the buffer if this is the first read after any other statement (including WebSphere MQ statements).
• Once the buffer has been emptied, subsequent Read Image statements that do not specify Position set ReadLen to 0, and leave the target image unchanged.

After a Read Image statement is issued, use the value of ReadLen to determine how many bytes were actually copied. If no bytes were copied, ReadLen=0.

The bytes in the image at offsets higher than the ReadLen value are unchanged.

To determine the number of bytes remaining, use the following formula:

bytes remaining = ($Buffer_Used - $Buffer_Position + 1)

Record positioning

If no position has been set prior to a Read Next, the position is assumed to be at the beginning of the file.

The record is positioned in the image according to the following rules:

• If the record is longer than the image, the record is truncated.
• If the record is smaller than the image, items beyond the end of the data are filled with the Initial value. An item that is partially filled by the input data is filled with the pad character for String and EFormat items and with binary zeros for Binary, Packed, Zoned, and Float items.
• When there are arrays with depending variables, each such array is filled with the number of elements specified in the depending variable. The remainder of the array is initialized according to the Initial clauses. The remaining data is move to the image following the array.
• If the length of the image is unknown because items or arrays have length or number of occurrences specified as Unknown, the block is filled with as much of the external record as fits in the remaining physical buffer space.

Length of the external record

The length of the external record is stored in the variable %imagename:ReadLen.

Previous identifications of lengths of items defined as length Unknown or number of occurrences of arrays defined with Occurs Unknown are lost. The Identify statement must be executed again to establish length or number of occurrences.

Usage notes

The Read Image statement with the Terminal option can be useful to obtain user input, and in some cases is more advantageous than $Read because it is independent of the argument string on an INCLUDE command. For example, consider this procedure:

PROCEDURE FOO begin %file is longstring %password is string len 255 %file = %(system):arguments:unspace:toUpper %password = - $read('Password?', 'TRANSPARENT')  ;* TRANSPARENT in case pwd ends, say, in a hyphen openC %file password %password end END PROC FOO

If the above procedure is invoked as:

INCLUDE FOO MYFILE

Then the user is not prompted, and no input is taken from the user. Instead, the string MYFILE, which is the first token in the INCLUDE command argument string, is returned as the value of $Read. However, in the following approach, the user is prompted to input the password value:

PROCEDURE FOO begin %file is longstring %password is string len 255 %file = %(system):arguments:unspace:toUpper image str s is string len 255 end image open terminal for input read image str from terminal prompt 'Password?' openC %file password %str:s end END PROC FOO

Release Position statement

The Release Position statement terminates a browse operation established by a Position statement.

Execution of a Release Position statement releases the VSAM string that maintains the current position in the file. The number of these strings is limited, and freeing the string as soon as the browse is finished allows other users to access the file.

Note: A Position statement automatically is released by another Position statement, a Read Image statement with a Key clause, a Close statement, or the end of the request.

Syntax

The format of the Release Position statement is:

Release Position {ext-filename | %variable}

Where:

ext-filename is the name of the external file used in the Position statement. A %variable also can be used to supply the external file name.

Write Image statement

The Write Image statement loads data into the Universal Buffer, or it writes an active image to a sequential file or to the terminal.

Syntax

The format of the Write Image statement is:

Write [Image] imagename On
[Buffer [Position=%pvariable | n] [Maxlen={%lvariable | n}]]
| {seq-filename | Terminal | %variable}

Where:

• imagename specifies a message to place in the message buffer.
• The On clause determines which use of the Write Image statement to employ: writing to a sequential file or the terminal, or writing Large Object data to the Universal Buffer.
• Buffer (formerly, and still accepted as Mq_Buffer) specifies the Universal Buffer area.
• %pvariable or n specifies where in the buffer to start the placement.
• Position must be in the range 1-16,777,216. If not, the operation returns $Status=10 and $StatusD=20.

  The starting position in the buffer is determined by:

  • Position=%pvariable, if that was specified.
  • $Buffer_Position, otherwise.
• Maxlen=%lvariable specifies the maximum number of bytes to copy from the image. The actual number copied is less than %lvariable, if the size of the image is less.

  Maxlen must be in the range 1-32,767. If not, the operation returns $Status=10 and $StatusD=19. The amount of data to copy is determined by:

  If Maxlen=%lvar is	Then copy...
  Not specified	Current length of the image.
  Specified	Lesser of %lvariable and the current length of the image.

• seq-filename specifies the name of the sequential file to which the image should be written. A %variable also can be used to supply the name of the sequential file.
• Terminal specifies that the image should be written to the terminal. A %variable also can be used to supply the word Terminal.

  If you specify the Position option on the Write Image statement, data type translation is not performed for the terminal output.

Usage

The Write Image statement is valid only if the file or terminal from which the record is read currently is open for OUTPUT, OUTPUT INPUT, or INOUT values.

Note: When the Write Image statement is used for a depending array, unused occurrences of the array are eliminated from the output.

If an MqPut or MqPut1 statement is issued with the Buffer option, the buffer must contain a message, otherwise the operation fails with a nonzero $Status value.

If the last WebSphere MQ operation was a successful put or get, then an MqPut or MqPut1 statement with the BUFFER options puts the message most recently processed. In all other cases, at least one Write Image imagename On Buffer statement must have been issued.

Note: Issue an MqPut statement with the Buffer option after a Write Image imagename On Buffer statement, otherwise $Status indicates there is no data in the buffer.

Image positioning

The data in the image is loaded into the buffer. Where the data is placed in the buffer depends on whether the Position option was specified.

If Position was not specified:

• On the first such Write Image after any other SOUL statement or WebSphere MQ statement, the data is loaded starting in the first-byte position in the buffer.
• On subsequent Write Image statements, data is loaded immediately following the data from the most recent WRITE.

If Position is specified as:

• Numeric value, expressed as either a constant or variable that indicates where in the buffer to begin to place the data, then the count starts from 1.
• Nonnumeric, less than one, or larger than the current size of the buffer, then the statement fails with a nonzero $Status value.

The ending position in the buffer is determined by the starting position, plus the amount of data to copy.

If the size of the user's BUFFER area is less than the ending position, the existing BUFFER area is expanded to a size equal to the ending position (data within the BUFFER area is preserved).

The data is copied from the image to the BUFFER area:

• $Buffer_Position is set to the byte after the last byte copied.
• $Buffer_Used is set according to the following rule: if data was written past the previous $Buffer_Used point, then $Buffer_Used is the point written to by the Write Image; otherwise, it is unchanged.

Error handling

Error conditions encountered during the processing of image I/O statements — Close, Open, Position, Read Image, Release Position, and Write Image — generate Model 204 error messages that are not displayed on the terminal.

The request should check for errors after the execution of each I/O statement by using the $Status function. The text of the most recently issued error message then can be retrieved by using the $Errmsg function. Refer to $ErrClr and $Status for more information.

$Status return codes

The values that can be returned by $Status are listed below:

Code	Description
0	The operation was successful. A return code of 0 also clears the message buffer. Therefore, the $Errmsg function, if called, returns a null string.
1	Either an end of file was detected by a Read Next statement or a matching key was not found for the criteria specified in a Read Key or Position statement. This code is only a warning; the request continues but cannot refer to the image before the next Read Key or Position statement.
2	A serious error has occurred such as an Open statement failure or an attempt to access an unopened file. The request continues, but the statement that generated the status code has not completed successfully. The failed statement cannot set an image active, resulting in the cancellation of the request if the image is referred to before being set active. The error that occurred can be retrieved by using $Errmsg to obtain the last counting or cancellation error message produced by Model 204.

Detecting ABEND codes in SOUL

When Model 204 intercepts an ABEND, the ABEND code and reason code are saved in the user's KOMM and can be accessed by the $Status and $StatusD $functions. The values of $Status and $StatusD are set as follows:

$function	Value	Where
$Status	System ABEND code	System code is not zero
$Status	User ABEND code	User code is not zero
$Status	255 (X'FF')	ABEND code => X'F00'
$StatusD	Concatenated values of the $Status values:	sss is the system ABEND code uuu is the user ABEND code rr is the ABEND reason code

If the ABEND is related to a communications I/O error, the SNA Communications Server (formerly VTAM), LU 6.2, or TCP/IP error routines set $Status and $StatusD with the result of the Terminal I/O and so override the ABEND code information.

Note: It is possible to get an ABEND code of all zeros. Some IBM system routines terminate with an ABEND U000 when they are invoked without APF authorization.

The ABEND code is not available in the z/VSE environment.

Sample requests

This section presents three examples illustrating the use of images in a request.

Using the READ KEY facility

The following request illustrates the use of the READ KEY facility. The printed record is the one with a VSAM key equal to a user-specified value.

BEGIN IMAGE EMP.REC CODE IS STRING LEN 8 JOB.DESC IS STRING LEN 50 NUM IS STRING LEN 7 DP * END IMAGE OPEN DATASET VSAMDS1 FOR INPUT IF $STATUS NE 0 THEN PRINT $Errmsg STOP END IF PROMPT: %KEY = $READ('ENTER KEY') IF %KEY = 'END' THEN JUMP TO EXIT END IF READ IMAGE EMP.REC FROM VSAMDS1 KEY EQ %KEY IF $STATUS EQ 1 THEN PRINT 'RECORD NOT FOUND' ELSEIF $STATUS EQ 2 THEN PRINT $Errmsg JUMP TO EXIT ELSE PRINT 'CODE = ' WITH %EMP.REC:CODE PRINT 'JOB DESCRIPTION = ' WITH %EMP.REC:JOB.DESC PRINT 'NUMBER = ' WITH %EMP.REC:NUM END IF JUMP TO PROMPT EXIT: CLOSE DATASET VSAMDS1 END

The preceding request could be rewritten in the manner shown in the next example to print information from ten successive records of the VSAM file.

Using a Position statement

The starting position in this example is established in the file through the use of the Position statement and a user-specified key.

BEGIN IMAGE EMP.REC CODE IS STRING LEN 8 JOB.DESC IS STRING LEN 50 NUM IS STRING LEN 7 DP * END IMAGE OPEN DATASET VSAMDS1 FOR INPUT IF $STATUS NE 0 THEN PRINT $Errmsg STOP END IF PROMPT: %KEY = $READ('ENTER KEY') IF %KEY = 'END' THEN JUMP TO EXIT END IF POSITION VSAMDS1 AT KEY GE %KEY FOR %CT FROM 1 TO 10 READ IMAGE EMP.REC FROM VSAMDS1 IF $STATUS EQ 1 THEN PRINT 'END OF FILE' JUMP TO PROMPT ELSEIF $STATUS EQ 2 THEN PRINT $Errmsg JUMP TO EXIT ELSE PRINT 'CODE = ' WITH %EMP.REC:CODE PRINT 'JOB DESCRIPTION = ' WITH %EMP.REC:JOB.DESC PRINT 'NUMBER = ' WITH %EMP.REC:NUM END IF END FOR JUMP TO PROMPT EXIT: CLOSE DATASET VSAMDS1 END

Example

The following request reads a sequential file that contains output from a previously issued Print All Information (PAI) statement. The foundset data is now in a data set. The request also handles non-PAI lines that might be found in the sequential file as separators; see the sample output that follows. The file being processed in this request contains PAI data for a CENSUS file.

BEGIN IMAGE PAI LINE IS STRING LEN 255 FIELDNAME IS STRING AT LINE LEN UNKNOWN SKIP 3 POSITIONS VALUE IS STRING LEN UNKNOWN END IMAGE OPEN DATASET OUTTAPE2 FOR INPUT IF $STATUS EQ 1 THEN JUMP TO DONE ELSEIF $STATUS EQ 2 THEN PRINT 'OPEN ERROR: ' WITH $Errmsg STOP END IF READ: READ PAI FROM OUTTAPE2 IF $STATUS EQ 1 THEN JUMP TO DONE ELSEIF $STATUS EQ 2 THEN PRINT 'READ ERROR: ' WITH $Errmsg STOP END IF %A = $INDEX(%PAI:LINE,' = ')-1 IF %A GE 0 THEN %B = %PAI:READLEN-%A-3 IDENTIFY %PAI:FIELDNAME LEN %A IDENTIFY %PAI:VALUE LEN %B PRINT 'FIELD= WITH %PAI:FIELDNAME WITH ' - WITH 'VALUE= AT 35 WITH %PAI:VALUE WITH ' ELSE PRINT %PAI:LINE END IF JUMP TO READ DONE: PRINT 'END OF INPUT FILE' END

The preceding request generates output in the format illustrated below. (This is the recommended format for file reorganization, as discussed in File reorganization and table compaction.)

* FIELD='HOUSEHOLD ID' VALUE='53690' FIELD='AGE' VALUE='21' FIELD='OCCUPATION' VALUE='CLERK' FIELD='SEX' VALUE='FEMALE' FIELD='PLACE SIZE' VALUE='50000' FIELD='RELATION' VALUE='UNRELATED' FIELD='FATHERS BIRTHPLACE' VALUE='UNITED STATES' FIELD='MOTHERS BIRTHPLACE' VALUE='UNITED STATES' FIELD='BIRTHPLACE' VALUE='NORTH CENTRAL REGION' FIELD='MOTHER TONGUE' VALUE='ENGLISH' FIELD='SCHOOL' VALUE='4 YEARS HIGH SCHOOL' FIELD='ROOMS' VALUE='GROUP QUARTERS' FIELD='FAMILY SIZE' VALUE='NOT IN A FAMILY' * FIELD='HOUSEHOLD ID' VALUE='42860' FIELD='AGE' VALUE='36' FIELD='OCCUPATION' VALUE='SALESMAN' FIELD='SEX' VALUE='MALE' FIELD='PLACE SIZE' VALUE='50000' FIELD='RELATION' VALUE='HEAD' FIELD='FATHERS BIRTHPLACE' VALUE='UNITED STATES' FIELD='MOTHERS BIRTHPLACE' VALUE='UNITED STATES' FIELD='BIRTHPLACE' VALUE='SOUTHERN REGION' FIELD='MOTHER TONGUE' VALUE='ENGLISH' FIELD='SCHOOL' VALUE='1-3 YEARS COLLEGE' FIELD='ROOMS' VALUE='4' FIELD='FAMILY SIZE' VALUE='4' END OF INPUT FILE