View source for Images

<div class="toclimit-3">

==Overview==
<p>
This article describes <b>images</b>, a feature of SOUL that allows:</p>
<ul>
<li>A request to read and process non-<var class="product">Model&nbsp;204</var> files, that is, sequential and VSAM files, and terminal input, such as a Host Language IFDIAL thread</li>

<li>A request to write to sequential files and terminals </li>

<li>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 <var class="product">Model&nbsp;204</var> </li>
</ul>
 
===Terminology===
<p>
Before reviewing the capabilities and requirements of images, you should be familiar with the following terms that are used throughout this discussion:</p>
<table>
<tr class="head">
<th>Term </th>
<th>Definition</th>
</tr>

<tr>
<td>Array</td>
<td>Ordered arrangement of data elements. Multiple occurrences of an item or a group of items. </td>
</tr>

<tr>
<td>Block </td>
<td>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.</td>
</tr>

<tr>
<td>Image</td>
<td>A description of the format of data in a block.</td>
</tr>

<tr>
<td>Item</td>
<td>An individual string or number in an image. </td>
</tr>
</table>
 
===Global images===
<p>
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.</p>
<p>
Although there are some differences in the way you use the DECLARE IMAGE statement, you generally define and use global images the same as you do non-global images. See [[Global features#Global images and screens|Global images and screens]] where a discussion of global screens, menus, and images begins.</p>

==Using images==
<p>
See [[Global features#Global images and screens|Global images and screens]] for a discussion of global images.</p>
 
===Reading external files or terminal input===
 
====Input sources====
<p>
The image feature lets a request read and process records from the following sources of input: </p>
<table>
<tr class="head">
<th>Input sources </th>
<th>Description</th>
</tr>

<tr>
<td>Sequential or VSAM files </td>
<td>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. 
<p>
For more information on the types of files and keys that can be used,
see the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command.    </p>
</td></tr>

<tr>
<td>Terminal </td>
<td>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 <var>[[IFDIAL (HLI function)|IFDIAL]]</var> function. </td></tr>
</table>

====External records====
<p>
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 <var class="product">Model&nbsp;204</var> records. </p>
<p>
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. User Language statements can refer to each item described in the image definition.</p>
 
====Reading records into an image====
<p>
User Language statements, which are documented beginning with [[#Processing images|Processing images]], let the request open the file, read records into the image, and close the file. </p>
<p>
For keyed VSAM files, the request can position the file to read sequentially starting with any record in the file.</p>

===Writing to sequential files or a terminal===
<p>
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. </p>
<p class="note"><b>Note:</b> 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.</p>
 
===Defining storage blocks===
<p>
You can define the data in a block of storage as an image. </p>
<p>
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 <var class="product">Model&nbsp;204</var> record, screen items, items from the current block or another block, and expressions. </p>
<p>
Each item defined in the image can be referred to by User Language statements.</p>
 
====Possible uses====
<p>
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:</p>
<ul>
<li>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.</li>

<li>Copy into an image fields in <var class="product">Model&nbsp;204</var> 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 <var class="product">Model&nbsp;204</var> 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.</li>

<li>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. </li>

<li>Pass data from one request to another.</li>

<li>You can manipulate more than one image at a time in an application, for example, in an HORIZON application involving simultaneous conversations.</li>

<li>You can use images to structure the local working storage of a request in a more disciplined manner than is possible with %variables.</li>
</ul>
 
==Defining an image==
 
===Managing blocks===
<p>
You must define the layout of the block before it can be used by the request. </p>
<p>
A block is defined by one or more images that describe the data in the block. </p>
<p>
Images describe blocks of data up to 32,767 bytes in length.   </p>
 
===Define an image before referring to it===
<p>
In a request, an image definition must precede any references to the image. </p>
 
===Understanding how data is described by images===
<p>
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:</p>
<ul>
<li>Using images, the application can access any piece of data in the block. As many as 255 images can describe the same block.</li>

<li>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).</li>

<li>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.</li>

<li>You can define the image items as strings or numbers. Numbers can have binary, floating point, packed decimal, zoned decimal, and exponential formats. <var class="product">Model&nbsp;204</var> automatically handles all data type conversions when referring to image items.</li>

<li>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.</li>

<li>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. </li>
</ul>

===Image components===
<p>
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:</p>
<ul>
<li>Image definitions</li>

<li>Item definitions</li>

<li>Array definitions</li>

<li>Reserved area definitions </li>
</ul>
<p>
Comments, blank lines, and INCLUDE statements can also be part of a block definition.  </p>
 
===Concurrent access to multiple records of the same format===
<p>
One image definition is required for each record to be accessed concurrently. </p>
<p>
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.</p>
 
==Image naming and reference conventions==
 
===Rules for image names===
<ul>
<li>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 <var class="product">Model&nbsp;204</var> reserved characters. Refer to [[Reserved words and characters]] for a complete list of reserved characters.</li>

<li>An image cannot have the same name as a screen or menu.</li>

<li>If IMAGE, MENU, or SCREEN is an image name, it must be preceded by the keyword IMAGE in READ IMAGE and PREPARE statements.  </li>
</ul>
 
===Rules for item names and array names===
<ul>
<li>Item and array names follow the same naming conventions as image names.</li>

<li>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.</li>

<li>An item (or array) name and its image name cannot have a combined length exceeding 253.   </li>
</ul>
 
===Rule for reserved item names===
<p>
The item name READLEN is reserved by <var class="product">Model&nbsp;204</var> to contain the length of the last record read into the block. This value can be obtained from the variable %imagename:READLEN. </p>
 
===Do not duplicate names in the same block===
<p>
Do not duplicate item, array, and image names within the same block. </p>
 
===References===
<p>
To identify the item uniquely, all references outside the image definition must include the image name and item name and must be specified in this format:</p>
<p class="syntax"><span class="term">%imagename</span>:<span class="term">itemname</span>
</p>
<p>
For example:</p>
<p class="code">%INVENTORY:PART.NO
</p>
<p>
identifies the item PART.NO in the image INVENTORY.     </p>
 
==IMAGE and END IMAGE statements==
<p>
The IMAGE statement starts the definition of the image. Each image can contain a description of the complete block or can redefine a portion of another image.</p>
 
====Syntax====
<p>
The format of the IMAGE statement is:</p>
<p class="syntax">IMAGE <span class="term">imagename</span> [AT {<span class="term">itemname</span> | <span class="term">imagname1</span> 
 | <span class="term">arrayname</span>} 
 | GLOBAL [PERMANENT | TEMPORARY] 
 | [PERMANENT | TEMPORARY] GLOBAL 
 | COMMON]
</p>
Where:
<ul>
<li><var class="term">imagename</var> 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 User Language statements in the request can subsequently refer to this name.</li>
 
<li>The AT clause is optional and specifies the starting location of a redefinition. If the AT clause is omitted, the image definition starts at the beginning of the block. The location can be defined by one of the following options:
<ul>
<li><var class="term">itemname</var> is the name of an item in a previously defined image in this block.</li>

<li><var class="term">imagename1</var> is the name of an image previously defined in this block.</li>

<li><var class="term">arrayname</var> is the name of an array in a previously defined image in this block. </li>
</ul>
 
<blockquote class="note"><p><b>Note:</b>
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.</p>
<ul>
<li>Specifying COMMON, or specifying neither COMMON nor GLOBAL, results in the image being stored in FSCB. Common elements, as well as DECLARE and COMMON, are discussed in detail in [[Subroutines#Subroutines|Subroutines]].   </li>
 
<li>GLOBAL specifies to store the image in GTBL. Global images have an implied scope of COMMON (see above). 
</li>
</ul>
</blockquote>
</li></ul>
 
====Restrictions to the GLOBAL option====
<p>
You must not specify the GLOBAL attribute for an image that has an image item defined with either of the following attributes:</p>
<ul>
<li>OCCURS UNKNOWN</li>

<li>LEN UNKNOWN</li>
</ul>
<p>
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.</p>
<ul>
<li>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.</li>

<li>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.
</li>
</ul>
 
===END IMAGE statement===
<p>
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.</p>
<p>
The format of this statement is:       </p>
<p class="code">END IMAGE
</p>
 
===Examples of image definitions===
 
====Single image definition====
<p>
An example of the definition of a single image follows:</p>
<p class="code">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
</p>
 
====Multiple image definition for the same block====
<p>
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.</p>
<p class="code">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
</p>
 
====Multiple image definition with shared items====
<p>
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.</p>
<p>
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 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.</p>
<p class="code">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
</p>
 
===Special considerations for multiple image blocks===
<p>
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.</p>
 
====Using uninitialized disk space====
<p>
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 entire block has already been defined, because LINE begins at the same place as PART1. </p>
<p class="code">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
</p>
<p>
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 $C2X) and automatically substituted the page number. </p>
<p class="code">02.142 MAY 22 10.11.11                                            PAGE 2
XXXXXXXXXX    2YYYYY    2ZZZZZ
%A:LINE = XXXXXXXXXX     YYYYY     ZZZZZ
$C2X(%A:LINE) = E7E7E7E7E7E7E70000000000E8E8E8E8E80000000000E9E9E9E9E9
</p>
 
====Using initialized disk space====
<p>
Refining the previous code, the spaces between PART 1 and PART2 and PART3 are initialized by the intervening SKIP statements.</p>
<p class="code">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
</p>
<p>
Now the output displays the expected results. The line that begins $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.</p>
<p class="code">02.142 MAY 22 10.12.26                                            PAGE 2
XXXXXXXXXX     YYYYY     ZZZZZ
%A:LINE = XXXXXXXXXX     YYYYY     ZZZZZ
$C2X(%A:LINE) = E7E7E7E7E7E7E74040404040E8E8E8E8E84040404040E9E9E9E9E9
</p>
 
==Defining image items==
<p>
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:</p>
<ul>
<li>Data type </li>
<li>Length </li>
<li>Position </li>
<li>Number of occurrences</li>
<li>Editing options</li>
</ul>
 
====Syntax====
<p>
The general format of an item definition is:</p>
<p class="syntax"><span class="term">itemname</span> [IS [TYPE] <span class="term">type</span> <span class="term">description</span>]
</p>
Where:
<ul>
<li><var class="term">itemname</var> is the name by which the item is referred to.</li>
 
<li>TYPE is an optional keyword.</li>
 
<li><var class="term">type</var> specifies the data type of the item. Data type options are:
<ul>
<li>String</li>
<li>Binary</li>
<li>Large Object data</li>
<li>Packed decimal</li>
<li>Zoned decimal</li>
<li>Floating point</li>
<li>Exponential notation </li>
</ul></li>

<li><var class="term">description</var> is the length, position, number of occurrences, and editing options specified for the item based on the data type. 
</li>
</ul>
<p>
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|Item definition examples]]:  </p>
<table>
<tr class="head">
<th>Term</th>
<th>Description</th>
</tr>

<tr>
<td>Numeric</td>
<td>All types except STRING are considered numeric.</td>
</tr>

<tr>
<td>NULL</td>
<td>Binary zeros.</td>
</tr>

<tr>
<td>Omitted</td>
<td>The option is omitted from the item description and no default is specified.</td>
</tr>

<tr>
<td>String</td>
<td>A string of characters. A string must be enclosed in single quotes if it contains any of the following characters: blank, =, (, ), <, >, or ^.</td>
</tr>

<tr>
<td>ZERO</td>
<td>Numeric zero of the correct format for numeric items. String and EFORMAT items are set to a single character zero.      </td>
</tr>
</table>
 
==Defining a string item==
 
====Syntax====
<p>
Define string items with this syntax: </p>
<p class="syntax">STRING {LEN {<span class="term">n</span> | UNKNOWN} [DP {<span class="term">k</span> | *}] | TO <span class="term">position</span>} 
 [PAD {BLANK | <span class="term">character</span> | NULL}] 
 [STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}] 
 [INITIAL {BLANK | string | ZERO | NULL}] 
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] 
 [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] 
 | UNKNOWN}]
</p>
Where:
<ul>
<li>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. </li>
 
<li>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.   </li>
 
<li>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.  
<ul>
<li>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. </li>

<li>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. </li>   
</ul></li>

<li>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. 
<p>
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.</p>
</li>

<li>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.    </li>
 
<li>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.   </li>
 
<li>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. 
</li>
</ul>
 
====AFTER and AT clauses====
<ul>
<li>The AFTER and AT clauses are optional and mutually exclusive. Their function is as follows:
<p>
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.   </p>
<p>
An AT clause defines the location of the item in the image as adjacent to an item or array or 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|DEFAULT SKIP statement]]). If position is used, the location is relative to the beginning of the image. </p>
<p>
The position option can have a value from 1 through 32767. The item or array named in the AT clause cannot have a DEPENDING ON option.    </p>
<p>
Consider the following restrictions when using an AFTER or AT clause:</p>
<ul>
<li>Outside of an array definition, the AFTER or AT clause cannot name an item inside the array.</li>

<li>Within an array definition, the AFTER or AT clause cannot name an item outside of the array. </li>

<li>If neither AFTER nor AT are specified, the item abuts the end of the preceding item or the start of the image.</li>
</ul>
</li>
</ul>
 
====OCCURS clause====
<ul>
<li>The OCCURS clause (optional) specifies that there are multiple occurrences of the item. The OCCURS clause options are as follows: 
<ul>
<li><var class="term">n</var> 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 <var class="term">n</var> 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.</li>

<li>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.   </li>

<li>UNKNOWN specifies that the number of occurrences of the item is determined by the User Language request and that the IDENTIFY statement establishes the number of occurrences.   </li>
</ul>
</li></ul>
 
==Defining a binary item==
 
====Syntax====
<p>
Define binary items with this syntax:   </p>
<p class="syntax">BINARY {LEN {<span class="term">n</span> | UNKNOWN} | BITS <span class="term">n</span> | TO <span class="term">position</span>} 
 [BP <span class="term">n</span>] 
 [SIGNED | UNSIGNED] [ALIGN] 
 [INITIAL {NULL | <span class="term">number</span> | BLANK | ZERO}] 
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] 
 [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] 
 | UNKNOWN}]
</p>
Where:
<ul>
<li>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.   </li>
 
<li>BITS specifies the length as 8, 16, 24, or 32 bits. </li>
 
<li>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.    </li>
 
<li>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.</li>
 
<li>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.  
<p class="note"><b>Note:</b>
If a negative number is read into an UNSIGNED BINARY item, <var class="product">Model&nbsp;204</var> uses the absolute value of that number. </p></li>

<li>ALIGN, optional, specifies that the item is aligned as follows: 
<ul>
<li>BINARY LEN 2 on a halfword boundary</li>
<li>BINARY LEN 4 on a fullword boundary </li>
<li>The ALIGN option is ignored for 1- and 3-byte BINARY items.</li>
</ul>
<p>
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 any parent array to make the length of each occurrence a multiple of the largest aligned item in the array.   </p>
<p>
The ALIGN option cannot be specified for an item:</p>
<ul>
<li>When length is defined as UNKNOWN. </li>
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN. </li>
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary.</li>
</ul></li>

<li>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.     </li>

<li>The AFTER and AT clauses are mutually exclusive and optionally define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>

<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].  
</li>
</ul>
 
==Defining a packed decimal item==
 
====Syntax====
<p>
Define packed decimal items with this syntax: </p>
<p class="syntax">PACKED {LEN {<span class="term">n</span> | UNKNOWN} | DIGITS <span class="term">n</span> | TO <span class="term">position</span>} 
 [DP <span class="term">n</span>] 
 [SIGNED | UNSIGNED] 
 [INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}] 
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] 
 [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}]
 | UNKNOWN}]
</p>
Where:
<ul>
<li>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. </li>
 
<li>DIGITS specifies the length as 1-15 decimal digits. </li>
 
<li>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.  </li>
 
<li>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.   </li>
 
<li>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.</li>
 
<li>UNSIGNED (optional) specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F.    </li>
 
<li>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.   </li>
 
<li>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|Defining a string item]].   </li>
 
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].    
</li>
</ul>
 
==Defining a zoned decimal item==
 
====Syntax====
<p>
Define zoned decimal items with this syntax:    </p>
<p class="syntax">ZONED {LEN {<span class="term">n</span> | UNKNOWN} | DIGITS <span class="term">n</span> | TO <span class="term">position</span>} 
 [DP <span class="term">n</span>] 
 [SIGNED | UNSIGNED] 
 [INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}] 
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] 
 [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] | UNKNOWN}]
</p>
Where:
<ul>
<li>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. </li>
 
<li>DIGITS specifies the length as 1-15 decimal digits. </li>
 
<li>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.    </li>
 
<li>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.   </li>
 
<li>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. </li>

<li>UNSIGNED, optional, specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F.    </li>
 
<li>INITIAL is optional and 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.     </li>
 
<li>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|Defining a string item]].     </li>
 
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].  
</li>
</ul>
 
==Defining a floating point item==
 
====Syntax====
<p class="syntax">FLOAT {LEN {<span class="term">n</span> | UNKNOWN} TO <span class="term">position</span> 
 [INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}] [ALIGN]
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}] 
 [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] | UNKNOWN}]
</p>
Where:
<ul>
<li>LEN specifies the length as either 4, 8, or 16 bytes or as UNKNOWN if the length is determined by the request and the IDENTIFY statement establishes the length. 
<p>
Although you can move 16-byte floating-point values between data sets and files, intermediate results and %variables inside User Language are 8 bytes long. </p>
<p>
Arithmetic manipulations and data conversions retain only 15 significant decimal digits in 8 bytes.</p>
</li>

<li>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.   </li>
 
<li>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.     </li>
 
<li>ALIGN, optional, specifies that the item is aligned as follows:  
<ul>
<li>FLOAT LEN 4 on a fullword boundary</li>
<li>FLOAT LEN 8 on a doubleword boundary</li>
<li>FLOAT LEN 16 on a doubleword boundary </li>
<li>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.   </li>
</ul>
<p>
The ALIGN option cannot be specified for an item: </p>
<ul>
<li>When length is defined a UNKNOWN.</li>
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN.  </li>
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary. </li>
</ul></li>

<li>The AFTER and AT clauses are mutually exclusive and optionally define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]].   </li>
 
<li>The OCCURS clause is optional and specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].   
</li>
</ul>
 
==Defining an exponential notation item==
 
====Syntax====
<p>
Define exponential notation items with this syntax:    </p>
<p class="syntax">EFORMAT {LEN {<span class="term">n</span> | UNKNOWN} | TO <span class="term">position</span>} 
 [PAD {BLANK | <span class="term">character</span> | NULL}] 
 [STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}] 
 [INITIAL {BLANK | <span class="term">string</span> | ZERO | NULL}] [DIGITS <span class="term">n</span>] 
 [DP <span class="term">n</span>] [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>}
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}]
 [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}] | UNKNOWN}]
</p>
Where:
<ul>
<li>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. </li>
 
<li>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.    </li>
 
<li>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.   </li>
 
<li>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.   </li>
 
<li>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.   </li>
  
<li>INITIAL is optional and 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.     </li>
 
<li>DIGITS specifies the maximum number of significant digits &mdash; 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.   </li>
 
<li>DP specifies the number of digits to be placed to the right of the decimal point when a value is moved into the item.   </li>
 
<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. See [[#Defining a string item|Defining a string item]], for a complete discussion.      </li>
 
<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. See [[#Defining a string item|Defining a string item]] for a complete discussion. 
</li>
</ul>
 
==Item definition examples==
 
===An image containing various item types===
<p class="code">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
</p>
 
===Using the AT and AFTER clauses===
<p class="code">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
</p>
<p>
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.     </p>
 
==Defining arrays==
<p>
An <var class="term">array</var> contains multiple occurrences of a single item or a group of items. </p>
 
===Array definition statements===
<p>
When an array is composed of a single item, the array can be defined by using the OCCURS clause on the item definition or an ARRAY statement. </p>
<p>
When an array is composed of more than one item, the array is defined by using an ARRAY statement and is followed by definitions of the items that compose each element of the array.              </p>
<p>
None of the items in an array or subordinate array can specify LEN UNKNOWN or OCCURS UNKNOWN.</p>
 
===Types of arrays===
<p>
The format of the ARRAY statement depends on which of the following types of arrays is being defined:</p>
<table>
<tr class="head">
<th>For type of array... </th>
<th>The number of occurrences in the array is...</th>
</tr>
<tr>
<td>Fixed occurrence </td>
<td>Constant.</td>
</tr>
<tr>
<td>Depending </td>
<td>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.</td>
</tr>
<tr>
<td>Unknown </td>
<td>Not known. The maximum number of occurrences must be specified during evaluation by using the [[#IDENTIFY statement|IDENTIFY statement]]. </td>
</tr>
</table>
 
===ARRAY and END ARRAY statements===
<p>
You define an array with an ARRAY statement. The definitions of items and subordinate arrays follow the ARRAY statement. </p>
<p>
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.   </p>
 
==Defining a fixed occurrence array==
<p>
A <var class="term">fixed occurrence array</var> 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.  </p>
 
====Syntax====
<p>
The format of the ARRAY statement used to define a fixed occurrence array is:</p>
<p class="syntax">ARRAY [<span class="term">arrayname</span>] OCCURS <span class="term">n</span> 
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}
</p>
Where:
<ul>
<li><var class="term">arrayname</var> (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.     </li>
 
<li><var class="term">n</var> is the number of occurrences of the items in the array, which can range from 1 to 32767.</li>
 
<li>AFTER and AT clauses are mutually exclusive and optionally specify the location of the array in the image. See [[#Defining a string item|Defining a string item]] for detailed information. 
</li>
</ul>

====Example====
<p>
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.</p>
<p class="code">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
</p>
<p>
The same image could be written as:</p>
<p class="code">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
</p>
 
==Defining a depending array==
<p>
A <var class="term">depending array</var> 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. </p>
 
===Depending variable===
<p>
A depending variable is used to specify the actual number of occurrences that exist in the record.   </p>
<p>
The depending variable is used in this manner:</p>
<ul>
<li>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.     </li>
 
<li>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.  
</li>
</ul>
<p>
If a subordinate array has a depending variable, the value of that variable applies to all occurrences of the outer array. </p>
 
====Restrictions====
<p>
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.</p>
 
====Syntax====
<p>
The form of the ARRAY statement used for defining a depending array is:</p>
<p class="syntax">ARRAY [<span class="term">arrayname</span>] OCCURS <span class="term">n</span> DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}
</p>
Where:
<ul>
<li><var class="term">arrayname</var>, 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.     </li>
 
<li><var class="term">n</var> is the number of occurrences of the items in the array, which can range from 1 to 32767.</li>
 
<li>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: 
<ul>
<li>Be an array element</li>
<li>Vary in length, that is, be defined with LEN UNKNOWN</li>
<li>Follow any varying length item or array in the image.   </li>
</ul></li>
</ul>

====Example====
<p>
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.</p>
<p class="code">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
</p>
<p>
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.       </p>
 
==Defining an unknown array==
<p>
An array must be defined as <var class="term">unknown</var> 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.   </p>
 
====Syntax====
<p>
The format of the ARRAY statement used for defining an unknown array is:</p>
<p class="syntax">ARRAY [<span class="term">arrayname</span>] OCCURS UNKNOWN 
 [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>} 
 | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imaginename1</span> 
 | <span class="term">arrayname</span>}]
</p>
Where:
<ul>
<li><var class="term">arrayname</var> 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.</li>
 
<li>The AFTER and AT clauses are mutually exclusive and optionally specify the location of the array in the image. See [[#Defining a string item|Defining a string item]] for detailed information. 
</li>
</ul>
 
====Example====
<p>
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.</p>
<p class="code">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
</p>
 
==Referring to array elements==
<p>
Individual items within an array are identified by subscripts. The <var class="term">subscript</var> is enclosed in parentheses and can be any expression that evaluates to a number from 1 to the maximum size of the array.  </p>
 
===Nested arrays===
<p>
If arrays are nested, subscripts are required for each nesting level and are separated by commas. The outermost array is the first subscript.</p>
 
====Example====
<p>
In this example, the fifth student in the second course would be referred to as COURSE.STUDENT(2,5).</p>
<p class="code">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
</p>
 
==Initialization of array values==
<p>
<var class="product">Model&nbsp;204</var> 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.</p>
 
====Example 1====
<p>
The following statement sets all elements in all dimensions to 0:</p>
<p class="code">%ARRAY.ITEM (*,*,*) = 0
</p>
 
====Example 2====
<p>
If an array is defined as occurs 3, occurs 4, occurs 2, <code>%ARRAY.ITEM(*,2,*) = 9</code> is equivalent to the following:</p>
<p class="code">%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
</p>
 
====Example 3====
<p>
The following example prints AAA and 100:</p>
<p class="code">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
</p>
 
====Example 4====
<p>
The asterisk is not valid on the right side of a User Language assignment statement. The following statement is invalid and causes a compilation error:</p>
<p class="code">%X = %ARRAY.ITEM(*,*,*)
</p>
 
==Using Large Object fields with a very large array==
<p>
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.</p>
<p>
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.</p>
<p>
With a Large Object field, you can directly address each item using the <offset>,<length> syntax available for Large Object fields.</p>
<p>
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.</p>
<p>
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.</p>

<p class="warn"><b>Cautionary usage note:</b> 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.</p>
 
==Defining reserved space==
<p>
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. </p>
<p>
Space is reserved automatically by an AT clause that places an item beyond the end of the last defined item.      </p>
 
===SKIP statement===
<p>
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.     </p>
 
====Syntax====
<p>
The format of the SKIP statement for reserving space is:</p>
<p class="syntax">[<span class="term">itemname</span> IS] SKIP <span class="term">n</span> POSITION[S] 
  [INITIAL {NULL | <span class="term">character</span> | BLANK}]
</p>
Where:
<ul>
<li>The <var class="term">itemname</var> <var>IS</var> clause (optional) names a reserved area that can be referred to by an AFTER or AT clause.</li>
 
<li><var class="term">n</var> is the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.</li>
 
<li>The INITIAL clause indicates the character with which the area is filled by PREPARE and IDENTIFY statements. Options are as follows:
<ul>
<li>character &mdash; a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as X'hh'</li>
<li>BLANK &mdash; white spaces</li>
<li>NULL &mdash; binary zeros </li>
</ul>
<p>
If the INITIAL clause is omitted, NULL is the default.   </p>
</li>
</ul>
 
====Example====
<p>
This sample SKIP statement reserves two bytes before the next image item: </p>
<p class="code">SKIP 2 POSITIONS
</p>
 
==DEFAULT TYPE and DEFAULT SKIP statements==
<p>
You can provide default values for image item options to eliminate repetition of these options on each item definition, using:     </p>
<ul>
<li>DEFAULT TYPE</li>
<li>DEFAULT SKIP </li>
</ul>
 
===DEFAULT TYPE statement===
<p>
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.   </p>
 
====Syntax====
<p>
The format of the DEFAULT TYPE statement is:</p>
<p class="syntax">DEFAULT [TYPE] <span class="term">type</span> <span class="term">options</span>
</p>
Where:
<ul>
<li>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.</li>
 
<li><var class="term">type</var> specifies the data type of the item. Valid values are STRING, BINARY, FLOAT, PACKED, ZONED, or EFORMAT.</li>
 
<li><var class="term">options</var> specifies any of the options that are valid for the item type except for the TO, AFTER, AT, and OCCURS clauses. 
</li>
</ul>
 
===DEFAULT SKIP statement===
<p>
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.</p>
 
====Syntax====
<p>
The format of the DEFAULT SKIP statement is:</p>
<p class="syntax">DEFAULT SKIP <span class="term">n</span> POSITION[S] 
  [INITIAL {NULL | '<span class="term">character</span>' | BLANK}]
</p>
Where:
<ul>
<li><var class="term">n</var> is a positive integer that specifies the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.</li>
 
<li>The INITIAL clause indicates the fill character for PREPARE and IDENTIFY statements. Options are as follows: 
<ul>
<li><var class="term">character</var> &mdash; a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as X'hh'</li>
<li>BLANK &mdash; white space</li>
<li>NULL &mdash; binary zeros </li>
</ul>
<p>
If the INITIAL clause is omitted, NULL is the default. </p>
</li>
</ul>
 
===Example of DEFAULT statements===
<p>
The following examples show how an image can be described without and then with DEFAULT statements.</p>
 
====Without DEFAULT statements====
<p class="code">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
</p>
 
====With DEFAULT statements====
<p class="code">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
</p>
 
==Processing images==
<p>
Once a block is defined, you can use the following statements to process external records and to manipulate a block of storage. </p>
<table>
<tr class="head">
<th>Statement</th>
<th>Action undertaken</th>
</tr>

<tr>
<td>CLOSE</td>
<td>Closes a sequential file, VSAM file, or terminal opened by the request.</td>
</tr>

<tr>
<td>IDENTIFY</td>
<td>Defines an active image and establishes the length for items or array occurrences defined as UNKNOWN.</td>
</tr>

<tr>
<td>OPEN</td>
<td>Opens a sequential file, VSAM file, or terminal for processing.</td>
</tr>

<tr>
<td>POSITION</td>
<td>Specifies the next record to be read sequentially in a VSAM KSDS file.</td>
</tr>

<tr>
<td>PREPARE</td>
<td>Initializes an image.</td>
</tr>

<tr>
<td>READ IMAGE</td>
<td>Reads a record from a sequential file, VSAM file, or terminal.</td>
</tr>

<tr>
<td>RELEASE POSITION</td>
<td>Terminates the browse operation established by a POSITION statement.</td>
</tr>

<tr>
<td>WRITE IMAGE</td>
<td>Writes a record to a sequential file or to a terminal.</td>
</tr>
</table>
 
===Key field for VSAM files===
<p>
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.</p>
<p>
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. </p>
<p>
An example of this technique for a VSAM file that has a 4-byte binary key is illustrated below:</p>
<p class="code">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
        .
        .
        .
</p>

==Close statement==
<p>
The <var>Close</var> statement lets the request close a sequential file, VSAM file, or a terminal opened by the request. </p>
 
====Syntax====
<p>
The format of the <var>Close</var> statement for external I/O is:</p>
<p class="syntax"><span class="literal">Close</span> {<span class="literal">Dataset</span> | <span class="literal">External</span>} {<span class="term">ext-filename</span> | <span class="term">%variable</span>}
 | [<span class="literal">External</span>] <span class="literal">Terminal</span>
</p>
Where:
<ul>
<li>You must specify either the <var>Dataset</var>, <var>External</var>, or <var>Terminal</var> keyword.</li>
 
<li>The <var>Dataset</var> keyword specifies that the entity to be closed is a non-<var class="product">Model&nbsp;204</var> file, that is, a sequential or VSAM file.    </li>
 
<li>The <var>External</var> keyword specifies that the entity to be closed is a non-<var class="product">Model&nbsp;204</var> file, that is, a sequential or VSAM file, or a terminal.    </li>
 
<li><var class="term">ext-filename</var> specifies the name of the sequential or VSAM file to close, that is, the name used in the <var>Open</var> statement. Also, a %variable can provide the file name.</li>
 
<li><var>Terminal</var> specifies that the terminal currently opened by the <var>Open</var> statement should be closed. Also, a %variable can supply the word <var>Terminal</var>.  
</li>
</ul>

===Closing a Model 204 file===
<p>
The <var>Close</var> statement can be used only for closing external files or terminals. To close a <var class="product">Model&nbsp;204</var> file, you may use the <var>[[$Close]]</var> function within a <var class="product">User Language</var> request, or the <var>[[CLOSE command|CLOSE]]</var> command outside a request.</p>
 
==IDENTIFY statement==
<p>
The IDENTIFY statement establishes: </p>
<ul>
<li>Active image, if multiple images define the same block.</li>
<li>Length of items that were defined as UNKNOWN.</li>
<li>Number of occurrences for arrays that were defined as UNKNOWN. </li>
</ul>
 
====Syntax====
<p>
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.</p>
<p class="syntax">IDENTIFY {[IMAGE] <span class="term">imagename</span> 
 | <span class="term">%imagename</span>:<span class="term">itemname</span> LEN {<span class="term">n</span> | <span class="term">%variable</span>} 
 | {<span class="term">%imagename</span>:<span class="term">arrayname</span> | <span class="term">%imagename</span>:<span class="term">itemname</span>}
   OCCURS {<span class="term">n</span> | <span class="term">%variable</span>}}
</p>
Where:
<ul>
<li><var class="term">imagename</var> refers to an image that was previously described in an image definition.</li>
 
<li><var class="term">%imagename</var>:<var class="term">itemname</var> is an item that was defined with LEN UNKNOWN or OCCURS UNKNOWN.</li>
 
<li>The LEN clause specifies the length in bytes of the item or a %variable that contains the length. The length cannot exceed 255 bytes. </li>
 
<li><var class="term">%imagename</var>:<var class="term">arrayname</var> is an array that was defined with OCCURS UNKNOWN.</li>
 
<li>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. 
</li>
</ul>
 
===Establishing an active image===
<p>
Use the following form of the IDENTIFY statement to switch the active image to the named imaged, when multiple images define the same block:</p>
<p class="syntax">IDENTIFY [IMAGE] <span class="term">imagename</span>
</p>
<p>
The IDENTIFY statement also initializes the items, if any, that were not initialized by a previous READ IMAGE or PREPARE statement. </p>
<p class="note"><b>Note:</b> Use the IDENTIFY statement instead of a PREPARE statement for requests in which you want to maintain data passed in an image.</p>
 
====Use with global images====
<p>
When used with global images, the IDENTIFY IMAGE statement, can cause request termination due to either: </p>
<ul>
<li>Definition mismatches. See [[Global features#Consistency checks performed|Consistency checks performed]] for a description.</li>
 
<li>Insufficient space in [[Defining_the_runtime_environment_(CCAIN)#Understanding the global variable table (GTBL)|GTBL]].
</li>
</ul>
<p>
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 [[Global features#Images and screen processing|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.</p>

===Establishing lengths for UNKNOWN items===
<p>
Use the following form of the IDENTIFY statement to set the length for items defined with LEN UNKNOWN:</p>
<p class="syntax">IDENTIFY <span class="term">%imaginename</span>:<span class="term">itemname</span> LEN {<span class="term">n</span> | <span class="term">%variable</span>}
</p>
<p>
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 to another image where the array is larger using assignment statements.</p>
 
===Establishing occurrences for UNKNOWN arrays===
<p>
Use the following form of the IDENTIFY statement to set the number of occurrences for arrays or items defined with OCCURS UNKNOWN:</p>
<p class="syntax">IDENTIFY {<span class="term">%imagename</span>:<span class="term">arrayname</span> 
 | <span class="term">%imagename</span>:<span class="term">itemname</span>} OCCURS {<span class="term">n</span> | <span class="term">%variable</span>}
</p>
<p>
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. </p>
<p>
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 to another image where the array is larger using assignment.</p>
 
==MODIFY BUFFER statement==
 
====Function====
<p>
Manages the Universal Buffer size and can also keep messages or overwrite them with a fill character.</p>
 
====Syntax====
<p class="syntax">MODIFY BUFFER [SIZE=<span class="term">n</span> | <span class="term">%variable</span> [PRESERVE | NOPRESERVE]] 
  [FILL [X'<span class="term">nn</span>' | C'<span class="term">x</span>'] | CLEAR]
</p>
Where:
<ul>
<li>BUFFER (formerly and still accepted as MQ_BUFFER) specifies the Universal Buffer area. </li>
 
<li>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.</li>
 
<li>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).  
<p>
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.</p>
</li>

<li>CLEAR option, the default, specifies to overwrite the buffer with X'00'.</li>
 
<li>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.
<p>
If the FILL or CLEAR option is specified, the behavior of MODIFY BUFFER statement depends on what other options are used:</p>
<table>
<tr class="head">
<th>If... </th>
<th>Then...</th>
</tr>

<tr>
<td>FILL/CLEAR, SIZE, and NOPRESERVE are specified, or FILL is specified without SIZE </td>
<td>Entire buffer is filled with the fill character.</td>
</tr>

<tr>
<td>FILL/CLEAR, SIZE, and PRESERVE are specified </td>
<td>Fill character is used to fill the new portion of the buffer after the preserved data only if the buffer size is increased. </td>
</tr>
</table>
</li>
</ul>
 
====Usage====
<p>
The MODIFY BUFFER statement requires that you specify at least one option. </p>
<p>
When you overwrite the contents of BUFFER area, the value of $Buffer_Used is set to zero and the value of $Buffer_Position is set to one. See [[$Buffer_Size#$Buffer_Size|$Buffer_Size]] and [[$Buffer_Used#$Buffer_Used|$Buffer_Used]].</p>
<p>
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.</p>

<div id="openExt"></div>

<div id="OPEN statement"></div>
==Open statement==
<!--Caution: <div>s above-->
 
<p>
The <var>Open</var> statement can be used to open a sequential file, VSAM file, or terminal for processing.    </p>
 
====DEFINE DATASET required====
<p>
Before a VSAM file or a DOS sequential file can be opened, it must previously have been
defined using the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command. </p>
 
====Syntax====
<p>
The format of the <var>Open</var> statement for external I/O is:</p>
{{Template:Open (External I/O) statement syntax}}
Where:
<ul>
<li>Either the <var>Dataset</var> or <var>External</var> keyword must be specified to open a sequential (non-<var class="product">Model 204</var>) file. <var>Dataset</var> and <var>External</var> should not be specified for opening <var class="product">Model 204</var> files. </li>
 
<li><var class="term">ext-filename</var> 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 <var>DEFINE DATASET</var> command or, for sequential files, the OS DDNAME or CMS FILEDEF. The external file name can be provided in a %variable.</li>
 
<li><var>Terminal</var> specifies that the entity to be opened is a terminal. The word <code>Terminal</code> can be provided in a %variable.    </li>
 
<li>The required <var>For</var> 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 <var>Input</var> to be read into an <var>Image</var> and opened for at least <var>Output</var> to write data from an <var>Image</var>.
<p>
The <var>Input Output</var>, <var>Output Input</var>, and <var>InOut</var> combination options are valid only for the <var>Terminal</var> keyword.  </p>
</li>
 
<li>The <var>Password</var> clause is required for only password protected VSAM data sets. The clause generates an error when used with an <var>Open Terminal</var> statement, but is ignored in all other cases.
<p>
With the <var>Password</var> 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. </p>
</li>
</ul>

===Usage notes===
 
====Open statement in remote context====
<p>
This form of the <var>Open</var> statement is not supported in remote context. Using the <var>At</var> keyword with any of the keywords <var>Dataset</var>, <var>External</var>, or <var>Terminal</var> generates the following error message, which is not displayed on the terminal, but can be retrieved with the <var>$Errmsg</var> function:</p>
<p class="code">M204.1497: Remote specification conflicts with open type
</p>
 
====Multiple Opens of external data sets====
<p>
An attempt to open an already open external data set results in request cancellation with the following error message:</p>
<p class="code">M204.2153 Dataset <i>name</i> is already open
</p>
 
====Clearing messages====
<p>
An <var>Open</var> statement resets
the messages accessed by the <var>[[$Fsterr]]</var> and <var>[[$Errmsg]]</var> functions.  You may also clear the messages
using the <var>[[$ErrClr]]</var> function.</p>
 
====See also====
<ul>
<li>An <var>[[Open statement|Open]]</var> statement without
the <var>Dataset</var> or <var>External</var> keyword is used to open a <var class="product">Model&nbsp;204</var> file or group, similar to the <var>OPEN</var> command (for example, the [[OPEN FILE command]]). </li>

<li>The <var>[[Dataset class|Dataset]]</var> class can also be used to access external data sets. </li>
</ul>

==POSITION statement==
<p>
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.   </p>
<p>
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 [[Global features#POSITION statement|POSITION statement]].</p>
 
====Syntax====
<p>
The format of the POSITION statement is:</p>
<p class="syntax">POSITION {<span class="term">ext-filename</span> | <span class="term">%variable</span>} 
  AT KEY <span class="term">operator</span> {<span class="term">value</span> | <span class="term">%variable</span>}
</p>
Where:
<ul>
<li><var class="term">ext-filename</var> is the name of the VSAM file specified in the OPEN statement. The name can be provided as the value of a %variable. 
<p>
If <var class="term">ext-filename</var> is provided as a literal, it cannot be the name of a found set or list.</p>
</li>

<li><var class="term">operator</var> 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.</li>
 
<li><var class="term">value</var> 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.
<p>
If <var class="term">value</var> 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. </p>
<p>
If the length of <var class="term">value</var> 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.</p>
<p>
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|Key field for VSAM files]].   </p>
</li>
</ul>
 
==<b id="PrepareStmtImage"></b>PREPARE statement==
<p>
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.    </p>
<p>
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.    </p>
 
====Syntax====
<p>
The format of the PREPARE statement is:</p>
<p class="syntax">PREPARE [IMAGE] <span class="term">imagename</span>
</p>
<p>
where <var class="term">imagename</var> refers to an image that was previously described in an image definition. The keyword IMAGE is required if imagename is IMAGE, MENU, or SCREEN.</p>
 
===Use with global images===
<p>
The PREPARE IMAGE statement, when used with global images, can cause request termination due to either: </p>
<ul>
<li>Definition mismatches (see [[Global features#Consistency checks performed|Consistency checks performed]] for a description for global images)</li>
 
<li>Insufficient space in [[Defining_the_runtime_environment_(CCAIN)#Understanding the global variable table (GTBL)|GTBL]].
</li>
</ul>

==<b id="READ IMAGE statement"></b><b id="Read Image statement"></b><b id="Read Image statement"></b>Read Image statement==
<p>
The <var>Read</var> <var>Image</var> 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 <var>Read</var> <var>Image</var> statement reads the contents of the Universal Buffer.   </p>
 
===Syntax===
{{Template:Read Image statement syntax}}
Where:
<ul>
<li><var class="term">imagename</var> is an image that was previously described in an image definition. The keyword <var>Image</var> is required if imagename is <var>Image</var>, <var>Menu</var>, or <var>Screen</var>. <var class="term">imagename</var> also specifies a message to read in the Universal Buffer area.</li>
 
<li>The <var>From</var> clause determines which use of the <var>Read</var> <var>Image</var> statement to employ:
<ul>
<li>Reading Large Object data from the Universal Buffer</li>
<li>Reading from a sequential file or the terminal</li>
</ul></li>
 
<li><var>Buffer</var> (formerly, and still accepted as <var>Mq_Buffer</var>) specifies the Universal Buffer area.</li>
 
<li><var>Position</var> must be in the range 1-16,777,216. If not, the operation returns <code>[[$Status]]=10</code> and <code>[[$StatusD]]=20</code> return codes. <var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to begin reading.
<p>
If <var>Position</var>=<var class="term">%pvariable</var> is specified and <var class="term">%pvariable</var> is greater than <var>[[$Buffer_Used]]</var>, the operation returns <code>$Status=10</code> and <code>$StatusD=20</code>.</p>
<p>
The starting position in the buffer is determined by <var>Position</var>=<var class="term">%pvar</var>, if that was specified; <var>[[$Buffer_Position]]</var>, otherwise.</p>
<p>
The ending position in the buffer is determined by the lowest of starting position, plus <var class="term">%lvariable</var>, if <var>Maxlen</var>=<var class="term">%lvariable</var> was specified as the value of <var>$Buffer_Used</var>.</p>
</li>
 
<li><var>Maxlen</var>=%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.
<p>
<var>Maxlen</var> must be in the range 1-32,767. If not, the operation returns <code>$Status=10</code> and <code>$StatusD=19</code>.</p>
</li>
 
<li><var class="term">ext-filename</var> 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.</li>
 
<li><var>Terminal</var> specifies that records are read from the terminal. The keyword <var>Terminal</var> can be provided as the value of a %variable.    </li>
 
<li>The optional <var>Prompt</var> clause is used with only the <var>Terminal</var> 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.
<p>
The <var>Prompt</var> string can be as many as 255 characters. The string can be provided as a string type %variable.</p>
</li>
 
<li>The <var>Next</var> option reads the next record in the file. <var>Next</var> is the default, if the <var>Key</var> clause is omitted. A <var>Read</var> <var>Image</var> statement with the <var>Next</var> option can be executed only following an <var>Open</var>, <var>Position</var>, or <var>Read</var> <var>Next</var> statement.    </li>
 
<li>The <var>Key</var> clause identifies the record to read. The <var>Key</var> clause is valid only for VSAM files and the value is converted to a string. A <var>Read</var> <var>Image</var> statement with the <var>Key</var> clause automatically performs a <var>Release</var> <var>Position</var>.
<p>
Key clause options are <var class="term">operator</var> and <var class="term">value</var>:</p>
<ul>
<li><var class="term">operator</var> 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: <code>=</code>, <code>>=</code>, <var>Eq</var>, or <var>Ge</var>.</li>
 
<li><var class="term">value</var> is the key that locates the record. It can be supplied in a %variable.
<p>
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 <code>>=</code> or <var>Ge</var>. If the operator is <code>=</code> or <var>Eq</var>,  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.</p>
</li>
</ul>
<p>
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|Key field for VSAM files]]. </p>
</li>
</ul>
 
===Usage===
<p>
This statement is valid only if the file or terminal from which the record is read is currently open for <var>Input</var>, <var>Input</var> <var>Output</var>, or <var>InOut</var>. <var>Read</var> <var>Image</var> processing reads data until the Universal Buffer is exhausted, or the image is filled. </p>
<p>
The part of the message selected is copied from the Universal Buffer to the image:</p>
<ul>
<li>Contents of the Universal Buffer are unchanged.</li>
 
<li><var>$Buffer_Used</var> is unchanged.</li>
 
<li><var>$Buffer_Position</var> is set to the byte after the last byte copied.</li>
 
<li>No error indication is given, if the image is not big enough to hold the data.
</li>
</ul>
 
===Buffer area positioning===
<p>
If <var>Position</var> is specified:</p>
<ul>
<li>Numeric value, expressed as either a constant or variable, indicates where in the buffer to begin reading; the count starts from 1. </li>
 
<li>Beyond the end of the data, then the image is unchanged; <var>ReadLen</var> is set to 0. </li>
 
<li>If the value is nonnumeric, less than one, or beyond the end of the data, then the statement fails with a nonzero <var>$Status</var> value.
</li>
</ul>
<p>
If the <var>Position</var> option is not specified:</p>
<ul>
<li>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). </li>
 
<li>Once the buffer has been emptied, subsequent <var>Read</var> <var>Image</var>
statements that do not specify <var>Position</var> set <var>ReadLen</var> to 0, and leave the target image unchanged.
</li>
</ul>
<p>
After a <var>Read</var> <var>Image</var> statement is issued, use the value of <var>ReadLen</var> to determine how many bytes were actually copied. If no bytes were copied, <var>ReadLen</var>=0.</p>
<p>
The bytes in the image at offsets higher than the <var>ReadLen</var> value are unchanged.</p>
<p>
To determine the number of bytes remaining, use the following formula: </p>
<p class="code">bytes remaining = ($Buffer_Used - $Buffer_Position + 1)
</p>
 
===Record positioning===
<p>
If no position has been set prior to a <var>Read</var> <var>Next</var>, the position is assumed to be at the beginning of the file.</p>
<p>
The record is positioned in the image according to the following rules:</p>
<ul>
<li>If the record is longer than the image, the record is truncated.</li>
 
<li>If the record is smaller than the image, items beyond the end of the data are filled with the <var>Initial</var> value. An item that is partially filled by the input data is filled with the pad character for <var>String</var> and <var>EFormat</var> items and with binary zeros for <var>Binary</var>, <var>Packed</var>, <var>Zoned</var>, and <var>Float</var> items.</li>
 
<li>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 <var>Initial</var> clauses. The remaining data is move to the image following the array.</li>
 
<li>If the length of the image is unknown because items or arrays have length or number of occurrences specified as <var>Unknown</var>, the block is filled with as much of the external record as fits in the remaining physical buffer space.
</li>
</ul>
 
===Length of the external record===
<p>
The length of the external record is stored in the variable <code><i>%imagename</i>:ReadLen</code>.   </p>
<p>
Previous identifications of lengths of items defined as length <var>Unknown</var> or number of occurrences of arrays defined with <var>Occurs</var> <var>Unknown</var> are lost. The <var>Identify</var> statement must be executed again to establish length or number of occurrences.    </p>

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

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

If the  above procedure is invoked as:

<p class="code">INCLUDE FOO MYFILE</p>

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

<p class="code">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
</p>

==RELEASE POSITION statement==
<p>
The RELEASE POSITION statement terminates a browse operation established by a POSITION statement. </p>
<p>
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.</p>
<p class="note"><b>Note:</b> 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.   </p>
 
===Syntax===
<p>
The format of the RELEASE POSITION statement is:</p>
<p class="syntax">RELEASE POSITION {<span class="term">ext-filename</span> | <span class="term">%variable</span>}
</p>
Where:
<p>
<var class="term">ext-filename</var> is the name of the external file used in the POSITION statement. A %variable also can be used to supply the external file name. </p>
 
==WRITE IMAGE statement==
<p>
The WRITE IMAGE statement loads data into the Universal Buffer or writes an active image to a sequential file or to the terminal.</p>
 
===Syntax===
<p>
The format of the WRITE IMAGE statement is:</p>
<p class="syntax">WRITE [IMAGE] <span class="term">imagename</span> ON 
      [BUFFER [POSITION=<span class="term">%pvariable</span> | <span class="term">n</span>] 
      [MAXLEN={<span class="term">%lvariable</span> | <span class="term">n</span>}]]
      | {<span class="term">seq-filename</span> | TERMINAL | <span class="term">%variable</span>}
</p>
Where:
<ul>
<li><var class="term">imagename</var> specifies a message to place in the message buffer.</li>
 
<li>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.</li>
 
<li>BUFFER (formerly, and still accepted as MQ_BUFFER) specifies the Universal Buffer area.</li>
 
<li><var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to start the placement.</li>
 
<li>POSITION must be in the range 1-16,777,216. If not, the operation returns $STATUS=10 and $STATUSD=20. 
<p>
The starting position in the buffer is determined by:</p>
<ul>
<li>POSITION=<var class="term">%pvariable</var>, if that was specified.</li>
<li>$Buffer_Position, otherwise.</li>
</ul></li>

<li>MAXLEN=<var class="term">%lvariable</var> specifies the maximum number of bytes to copy from the image. The actual number copied is less than <var class="term">%lvariable</var>, if the size of the image is less. 
<p>
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:</p>
<table>
<tr class="head">
<th>If MAXLEN=<i>%lvar</i> is </th>
<th>Then copy...</th>
</tr>

<tr>
<td>Not specified </td>
<td>Current length of the image.</td>
</tr>

<tr>
<td>Specified </td>
<td>Lesser of %lvariable and the current length of the image.</td>
</tr>
</table>
</li>
 
<li><var class="term">seq-filename</var> 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.</li>
 
<li>TERMINAL specifies that the image should be written to the terminal. A %variable also can be used to supply the word TERMINAL.  
<p>
If you specify the TERMINAL option on the WRITE IMAGE statement, data type translation is not performed for the terminal output.   </p>
</li>
</ul>

===Usage===
<p>
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. </p>
<p class="note"><b>Note:</b> When the WRITE IMAGE statement is used for a depending array, unused occurrences of the array are eliminated from the output.</p>
<p>
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.</p>
<p>
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.</p>
<p class="note"><b>Note:</b> 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.</p>
 
===Image positioning===
<p>
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. </p>
<p>
If POSITION was not specified:</p>
<ul>
<li>On the first such WRITE IMAGE after any other User Language statement or WebSphere MQ statement, the data is loaded starting in the first-byte position in the buffer.</li>
 
<li>On subsequent WRITE IMAGE statements, data is loaded immediately following the data from the most recent WRITE. 
</li>
</ul>
<p>
If POSITION is specified as:</p>
<ul>
<li>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. </li>
 
<li>Nonnumeric, less than one, or larger than the current size of the buffer, then the statement fails with a nonzero $STATUS value. 
</li>
</ul>
<p>
The ending position in the buffer is determined by the starting position, plus the amount of data to copy.</p>
<p>
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).</p>
<p>
The data is copied from the image to the BUFFER area:</p>
<ul>
<li>$Buffer_Position is set to the byte after the last byte copied.</li>
 
<li>$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. 
</li>
</ul>

==Error handling==
<p>
Error conditions encountered during the processing of image I/O statements &mdash; <var>Close</var>, <var>Open</var>, <var>Position</var>, <var>Read Image</var>, <var>Release Position</var>, and <var>Write Image</var> &mdash; generate <var class="product">Model&nbsp;204</var> error messages that are not displayed on the terminal. </p>
<p>
The request should check for errors after the execution of each I/O statement by using the <var>$Status</var> function. The text of the most recently issued error message then can be retrieved by using the <var>[[$Errmsg]]</var> function. Refer to <var>[[$ErrClr]]</var> and <var>[[$Status]]</var> for more information.   </p>
 
===$Status return codes===
<p>
The values that can be returned by <var>$Status</var> are listed below:</p>
<table>
<tr class="head">
<th>Code </th>
<th>Description</th>
</tr>

<tr>
<td>0</td>
<td>The operation was successful. A return code of 0 also clears the message buffer. Therefore, the <var>$Errmsg</var> function, if called, returns a null string.</td>
</tr>

<tr>
<td>1</td>
<td>Either an end of file was detected by a <var>Read Next</var> statement or a matching key was not found for the criteria specified in a <var>Read Key</var> or <var>Position</var> statement. 
<p>
This code is only a warning; the request continues but cannot refer to the image before the next <var>Read Key</var> or <var>Position</var> statement.</p>
</td></tr>

<tr>
<td>2</td>
<td>A serious error has occurred such as an <var>Open</var> 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. 
<p>
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. </p>
<p>
The error that occurred can be retrieved by using <var>$Errmsg</var> to obtain the last counting or cancellation error message produced by <var class="product">Model&nbsp;204</var>.  </p>
</td></tr>
</table>
 
===Detecting ABEND codes in User Language===
<p>
When <var class="product">Model&nbsp;204</var> intercepts an ABEND, the ABEND code and reason code are saved in the user's KOMM and can be accessed by the <var>$Status</var> and <var>[[$StatusD]]</var> $functions. The values of <var>$Status</var> and <var>$StatusD</var> are set as follows:</p>
<table>
<tr class="head">
<th>$function</th>
<th>Value</th>
<th>Where</th>
</tr>

<tr>
<td>$Status</td>
<td>System ABEND code</td>
<td>System code is not zero</td>
</tr>

<tr>
<td>$Status</td>
<td>User ABEND code</td>
<td>User code is not zero</td>
</tr>

<tr>
<td>$Status</td>
<td>255 (X'FF')</td>
<td>ABEND code => X'F00'</td>
</tr>

<tr>
<td>$StatusD</td>
<td>Concatenated values of the $Status values:</td>
<td><var class="term">sss</var> is the system ABEND code
<p>
<var class="term">uuu</var> is the user ABEND code</p>
<p>
<var class="term">rr</var> is the ABEND reason code</p>
</td></tr>
</table>
<p>
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 <var>$Status</var> and <var>$StatusD</var> with the result of the Terminal I/O and so override the ABEND code information.</p>
<p class="note"><b>Note:</b> 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.</p>
<p>
The ABEND code is not available in the z/VSE environment.</p>

==Sample requests==
<p>
This section presents three examples illustrating the use of images in a request.</p>
 
===Using the READ KEY facility===
<p>
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.</p>
<p class="code">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
</p>
<p>
The preceding request could be rewritten in the manner shown in Example 2 to print information from ten successive records of the VSAM file. </p>
 
===Using a POSITION statement===
<p>
The starting position in this example is established in the file through the use of the <var>Position</var> statement and a user-specified key.</p>
<p class="code">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
</p>
 
===Example===
<p>
The following request reads a sequential file that contains output from a previously issued <var>Print All Information</var> (<var>PAI</var>) statement. The foundset data is now in a data set. The request also handles non-<var>PAI</var> 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 <var>PAI</var> data for a <code>CENSUS</code> file.</p>
<p class="code">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
</p>
<p>
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]].)</p>
<p class="code"><b></b>*
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'
<b></b>*
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
</p>
 
</div> <!-- end of toc limit div -->

[[Category:SOUL]]