Images: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(64 intermediate revisions by 6 users not shown)
Line 3: Line 3:
==Overview==
==Overview==
<p>
<p>
This article describes a feature of User Language, called images, that allows:</p>
This article describes <b>images</b>, a feature of SOUL that allows:</p>
<ul>
<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 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>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>
<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>
</ul>
Line 18: Line 20:
<th>Definition</th>
<th>Definition</th>
</tr>
</tr>
<tr>
<tr>
<td>Array</td>
<td>Array</td>
<td>Ordered arrangement of data elements. Multiple occurrences of an item or a group of items. </td>
<td>Ordered arrangement of data elements. Multiple occurrences of an item or a group of items. </td>
</tr>
</tr>
<tr>
<tr>
<td>Block </td>
<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>
<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>
<tr>
<tr>
<td>Image</td>
<td>Image</td>
<td>A description of the format of data in a block.</td>
<td>A description of the format of data in a block.</td>
</tr>
</tr>
<tr>
<tr>
<td>Item</td>
<td>Item</td>
Line 40: Line 46:
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>
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>
<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>
Although there are some differences in the way you use a <var>Declare Image</var> 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==
==Using images==
<p>
<p>
Line 50: Line 56:
====Input sources====
====Input sources====
<p>
<p>
The image feature lets a request read and process records from the following sources of input:       </p>
The image feature lets a request read and process records from the following sources of input: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 56: Line 62:
<th>Description</th>
<th>Description</th>
</tr>
</tr>
<tr>
<tr>
<td>Sequential or
<td>Sequential or VSAM files </td>
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.  
<td>
<p>
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>
<p>
<p>
For more information on the types of files and keys that can be used,
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>
see the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command.    </p>
</td>
</td></tr>
</tr>
 
<tr>
<tr>
<td>Terminal </td>
<td>Terminal </td>
<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>
<p>
Terminal input can be read and processed. A terminal can consist of the physical device on which the request is run, or a User Language connection that has been made from a Host Language application program by using the IFDIAL function. </p>
<p>
For more information on IFDIAL, refer to the <var class="book">Rocket Model&nbsp;204 Host Language Interface Reference Manual</var>. </p>
</td>
</tr>
</table>
</table>
 
====External records====
====External records====
<p>
<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>
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>
<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>
The format of the external record is described by a structure called an image. Multiple descriptions of a record are allowed, as discussed later in this article. SOUL statements can refer to each item described in the image definition.</p>
   
   
====Reading records into an image====
====Reading records into an image====
<p>
<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>
SOUL 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>
<p>
For keyed VSAM files, the request can position the file to read sequentially starting with any record in the file.</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===
===Writing to sequential files or a terminal===
<p>
<p>
Line 101: Line 99:
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>
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>
<p>
Each item defined in the image can be referred to by User Language statements.</p>
Each item defined in the image can be referred to by SOUL statements. </p>
   
   
====Possible uses====
====Possible uses====
Line 109: Line 107:
<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>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>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 <var>$Pack</var> 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>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>
Line 115: Line 113:
<li>Pass data from one request to another.</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 manipulate more than one image at a time in an application, for example, in a [[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>
<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>
</ul>
   
   
Line 124: Line 122:
===Managing blocks===
===Managing blocks===
<p>
<p>
You must define the layout of the block before it can be used by the request. </p>
You must define the layout of an image block before it can be used by the request. </p>
<p>
<p>
A block is defined by one or more images that describe the data in the block. </p>
A block is defined by one or more images that describe the data in the block. </p>
Line 140: Line 138:
<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>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.</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 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>
Line 146: Line 144:
<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 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 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>
<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>
</ul>
 
===Image components===
===Image components===
<p>
<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>
Each block definition must begin with an <var>Image</var> statement and end with an <var>End Image</var> statement. Between these statements, the following components are used to describe the contents of the block: </p>
<ul>
<ul>
<li>Image definitions</li>
<li>Image definitions</li>
Line 164: Line 162:
</ul>
</ul>
<p>
<p>
Comments, blank lines, and INCLUDE statements can also be part of a block definition.  </p>
Comments, blank lines, and <var>Include</var> statements can also be part of a block definition.  </p>
   
   
===Concurrent access to multiple records of the same format===
===Concurrent access to multiple records of the same format===
Line 170: Line 168:
One image definition is required for each record to be accessed concurrently. </p>
One image definition is required for each record to be accessed concurrently. </p>
<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>
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 <var>Include</var> statement inside the image definition. </p>
   
   
==Image naming and reference conventions==
==Image naming and reference conventions==
Line 176: Line 174:
===Rules for image names===
===Rules for image names===
<ul>
<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 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>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>
<li>If <code>Image</code>, <code>Menu</code>, or <code>Screen</code> is an image name, it must be preceded by the keyword <var>Image</var> in <var>Read Image</var> and <var>Prepare</var> statements.  </li>
</ul>
</ul>
   
   
Line 187: Line 185:
<li>Item and array names follow the same naming conventions as image names.</li>
<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>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>
<li>An item (or array) name and its image name cannot have a combined length exceeding 253. </li>
</ul>
</ul>
   
   
===Rule for reserved item names===
===Rule for reserved item names===
<p>
<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>
The item name <code>ReadLen</code> 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 <code>%<i>imagename</i>:ReadLen</code>. </p>
   
   
===Do not duplicate names in the same block===
===Do not duplicate names in the same block===
Line 202: Line 200:
===References===
===References===
<p>
<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>
To identify the item uniquely, all references outside the image definition must include the image name and item name, and they must be specified in this format:  
<p class="syntax"><span class="term">%imagename</span>:<span class="term">itemname</span>
</p>
<p class="syntax">%<span class="term">imagename</span>:<span class="term">itemname</span>
</p>
</p>
<p>
<p>
Line 210: Line 209:
</p>
</p>
<p>
<p>
identifies the item PART.NO in the image INVENTORY.     </p>
identifies the item <code>PART.NO</code> in the image <code>INVENTORY</code>. </p>
   
   
==IMAGE and END IMAGE statements==
==Image and End Image statements==
<p>
<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>
The <var>Image</var> statement starts the definition of an image block or of an additional image within the block. Each image can contain a description of the complete block, or it can redefine a portion of a preceding image in the block. An [[#End Image statemen|End Image statement]] completes the image block. </p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The format of the IMAGE statement is:</p>
The format of the <var>Image</var> block is:
<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>
</p>
Where:
{{Template:Image statement syntax}}
<p>
Where: </p>
<ul>
<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><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 <var>Image</var> statement is assigned to the image being defined; other SOUL 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:
<li><var>Namesave</var> is meaningful only for images used by certain $functions and OO methods: <var>$Field_Image</var>, <var>$Field_ListI</var>, and <var>AppendFieldImages</var>. </li>
 
<li><var>Global</var> specifies to store the image in GTBL. Global images have an implied scope of <var>Common</var> (see below).  
<blockquote class="note">
<p><b>Note:</b>
</p>
<ul>
<li>You must not specify the <var>Global</var> attribute for an image that has an image item defined with either of the following attributes:  
<ul>
<ul>
<li><var class="term">itemname</var> is the name of an item in a previously defined image in this block.</li>
<li><var>Occurs Unknown</var> </li>


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


<li><var class="term">arrayname</var> is the name of an array in a previously defined image in this block. </li>
<li>Images that share a block must have the same scope. For multi-image blocks, you can specify only the first image as <var>Global</var>; you must not specify subsequent images in a multi-image block as <var>Global</var>. Specifying the first image as <var>Global</var>, declares the entire block of images as <var>Global</var>. The same behavior and restrictions apply to <var>Common</var> images in a block. </li>
</ul>
</ul>
</blockquote></li>
<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>
<li><var>Permanent</var> 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>
<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><var>Temporary</var> can be used with only global images. <var>Temporary</var> global images are allocated in GTBL, but are deleted at request termination. For example, use a <var>Temporary</var> global image when you do not need to pass the image to another request; using <var>Temporary</var> global images eliminates the need to explicitly delete globals that do not need to persist. </li>
 
<li>GLOBAL specifies to store the image in GTBL. Global images have an implied scope of COMMON (see above).
<li><var>Common</var> images, or images that are neither <var>Common</var> nor <var>Global</var>, are stored in FSCB.  
</li>
<p>
</ul>
As described above for the <var>Global</var> option, you can specify only the first image in a multi-image block as <var>Common</var>, and you must not specify subsequent images in that block as <var>Common</var>. </p>
</blockquote>
</li></ul>
====Restrictions to the GLOBAL option====
<p>
<p>
You must not specify the GLOBAL attribute for an image that has an image item defined with either of the following attributes:</p>
Common elements, as well as <var>Declare</var> and <var>Common</var>, are discussed in detail in [[Subroutines#Subroutines|Subroutines]]. </p></li>
 
<li><var class="term">imageComponent</var> is any of the following (which are described in detail on this page):
<ul>
<ul>
<li>OCCURS UNKNOWN</li>
<li>Item definition</li>
 
<li>Array definition</li>
 
<li>Reserved area definition </li>
 
<li>Comment, blank line, or <var>Include</var> statement </li>
 
<li>Image definition (multiple-image block) </li>
</ul></li>


<li>LEN UNKNOWN</li>
<li>The <var>At</var> clause is optional and specifies the starting location of a redefinition (that is, <var>At</var> is not suitable for the initial image in the block). If the <var>At</var> clause is omitted, the definition of this additional image starts at the beginning of the block. The location can be defined by one of the following options:
</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>
<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><var class="term">itemname</var> is the name of an item in a previously defined image in this block.</li>
 
<li><var class="term">imagename</var> is the name of an image previously defined in this block.</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><var class="term">arrayname</var> is the name of an array in a previously defined image in this block. </li>
</li>
</ul>
</ul>
   
   
===END IMAGE statement===
<p class="note"><b>Note:</b>
You cannot use the <var>At</var> clause with a <var>Global</var> image, since you can only define the first image in a multi-image block as a global image. </p></li>
</ul>
 
===End Image statement===
<p>
<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>
The <var>End Image</var> statement must be the last statement in an image definition. <var>End Image</var> terminates the definition of all images that describe the same block. </p>
<p>
<p>
The format of this statement is:       </p>
The format of this statement is:  
<p class="code">END IMAGE
</p>
<p class="syntax">End Image
</p>
</p>
 
===Examples of image definitions===
===Examples of image definitions===
   
   
====Single image definition====
====Single image definition====
<p>
<p>
An example of the definition of a single image follows:</p>
An example of the definition of a single image follows:  
</p>
<p class="code">IMAGE GENERAL.LEDGER.RECORD
<p class="code">IMAGE GENERAL.LEDGER.RECORD
       GL.RECORD.TYPE  IS STRING LEN 1
       GL.RECORD.TYPE  IS STRING LEN 1
Line 288: Line 303:
====Multiple image definition for the same block====
====Multiple image definition for the same block====
<p>
<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>
The following example illustrates two images that define the same block. Each image completely defines the block, with the items named <code>GL.RECORD.TYPE</code> and <code>AR.RECORD.TYPE</code> both located at the first byte in the block.
</p>
<p class="code">IMAGE GENERAL.LEDGER.RECORD
<p class="code">IMAGE GENERAL.LEDGER.RECORD
       GL.RECORD.TYPE  IS STRING LEN 1
       GL.RECORD.TYPE  IS STRING LEN 1
Line 302: Line 318:
====Multiple image definition with shared items====
====Multiple image definition with shared items====
<p>
<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>
When an image redefines part of another image, the <var>At</var> 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 <var>Image</var> statement to create the complete image description.</p>
<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>
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 <code>RECORD.TYPE</code> is shared by both images, and it can be referred to by prefixing the item name by either image name. The items <code>GL.NUMBER</code> and <code>AR.ACCT.NO</code> both begin at position 2 in the block.  
</p>
<p class="code">IMAGE GENERAL.LEDGER.RECORD
<p class="code">IMAGE GENERAL.LEDGER.RECORD
       GL.RECORD.TYPE  IS STRING LEN 1
       GL.RECORD.TYPE  IS STRING LEN 1
Line 312: Line 329:
       AR.ACCT.NO      IS STRING LEN 6
       AR.ACCT.NO      IS STRING LEN 6
       AR.BALANCE      IS PACKED DIGITS 9 DP 2
       AR.BALANCE      IS PACKED DIGITS 9 DP 2
END IMAGE
END IMAGE </p>
</p>
<!-- above example is in Proc SOUL.DNC.001.QA from file QALOC in ULSPFDNC (2018/05/24 7:03:54 DNC) -->
   
   
===Special considerations for multiple image blocks===
===Special considerations for multiple-image blocks===
<p>
<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>
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====
====Using uninitialized disk space====
<p>
<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>
In the following multiple-image block, <code>PART1</code>, <code>PART2</code>, and <code>PART3</code> define parts of the block without defining or initializing the space between them. When <code>LINE</code> is defined, which encompasses the entire block, the system assumes that the entire block has already been defined, because <code>LINE</code> begins at the same place as <code>PART1</code>. </p>
<p class="code">R HDRCTL 0
<p class="code">R HDRCTL 0
BEGIN
BEGIN
Line 345: Line 362:
</p>
</p>
<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>
However, when output from the previous procedure is displayed, a stray numeral two appears twice in the header. This system read the string of zeros for the uninitialized space in the header (shown in the line that begins with <code>$C2X</code>) and automatically substituted the page number. </p>
<p class="code">02.142 MAY 22 10.11.11                                            PAGE 2
<p class="output">02.142 MAY 22 10.11.11                                            PAGE 2
XXXXXXXXXX    2YYYYY    2ZZZZZ
XXXXXXXXXX    2YYYYY    2ZZZZZ
%A:LINE = XXXXXXXXXX    YYYYY    ZZZZZ
%A:LINE = XXXXXXXXXX    YYYYY    ZZZZZ
Line 354: Line 371:
====Using initialized disk space====
====Using initialized disk space====
<p>
<p>
Refining the previous code, the spaces between PART 1 and PART2 and PART3 are initialized by the intervening SKIP statements.</p>
Refining the previous code, the spaces between <code>PART1</code>, <code>PART2</code>, and <code>PART3</code> are initialized by the intervening <var>Skip</var> statements: </p>
<p class="code">R HDRCTL 0
<p class="code">R HDRCTL 0
BEGIN
BEGIN
Line 380: Line 397:
</p>
</p>
<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>
Now the output displays the expected results. The line that begins with <code>$C2X</code> 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
<p class="output">02.142 MAY 22 10.12.26                                            PAGE 2
XXXXXXXXXX    YYYYY    ZZZZZ
XXXXXXXXXX    YYYYY    ZZZZZ
%A:LINE = XXXXXXXXXX    YYYYY    ZZZZZ
%A:LINE = XXXXXXXXXX    YYYYY    ZZZZZ
$C2X(%A:LINE) = E7E7E7E7E7E7E74040404040E8E8E8E8E84040404040E9E9E9E9E9
$C2X(%A:LINE) = E7E7E7E7E7E7E74040404040E8E8E8E8E84040404040E9E9E9E9E9
</p>
</p>
 
==Defining image items==
==<b id="imageItems"></b>Defining image items==
<p>
<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>
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>
Line 400: Line 417:
====Syntax====
====Syntax====
<p>
<p>
The general format of an item definition is:</p>
The general format of an item definition is:
<p class="syntax"><span class="term">itemname</span> [IS [TYPE] <span class="term">type</span> <span class="term">description</span>]
</p>
<p class="syntax"><span class="term">itemname</span> [Is [Type] <span class="term">type</span> <span class="term">description</span>]
</p>
</p>
Where:
Where:
Line 407: Line 425:
<li><var class="term">itemname</var> is the name by which the item is referred to.</li>
<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>Type</var> is an optional keyword.</li>
   
   
<li><var class="term">type</var> specifies the data type of the item. Data type options are:
<li><var class="term">type</var> specifies the data type of the item. Data type options are:
Line 433: Line 451:
<tr>
<tr>
<td>Numeric</td>
<td>Numeric</td>
<td>All types except STRING are considered numeric.</td>
<td>All types except String are considered numeric.</td>
</tr>
</tr>


<tr>
<tr>
<td>NULL</td>
<td>Null</td>
<td>Binary zeros.</td>
<td>Binary zeros.</td>
</tr>
</tr>
Line 448: Line 466:
<tr>
<tr>
<td>String</td>
<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>
<td>A string of characters. A string must be enclosed in single quotes if it contains any of the following characters: blank, <b>=</b>, <b>(</b>, <b>)</b>, <b><</b>, <b>></b>, or <b>^</b>.</td>
</tr>
</tr>


<tr>
<tr>
<td>ZERO</td>
<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>
<td>Numeric zero of the correct format for numeric items. String and EFORMAT items are set to a single character zero. </td>
</tr>
</tr>
</table>
</table>
   
   
==Defining a string item==
===Defining a string item===
   
   
====Syntax====
====Syntax====
<p>
<p>
Define string items with this 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>}  
<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}]  
  [Pad {Blank | <span class="term">character</span> | Null}]  
  [STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}]  
  [Strip | NoStrip] [Justify {Left | Right}]  
  [INITIAL {BLANK | string | ZERO | NULL}]  
  [Initial {Blank | string | Zero | Null}]  
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</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>}]  
  | 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>}]  
  [Occurs {<span class="term">n</span> [Depending On {<span class="term">itemname</span> | <span class="term">%variable</span>}]  
  | UNKNOWN}]
  | Unknown}]
</p>
</p>
Where:
Where:
<ul>
<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><var>Len</var> specifies the length either as 1-255 bytes or as <var>Unknown</var>, if the length is determined by the request and the <var>Identify</var> 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><var>To</var> specifies the last byte position of the item in the image as a number from 1 to 32767. The length (<var>Len</var>) or end (<var>To</var>) position of the item is required unless the length has been specified in a <var>Default</var> 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.   
<li><var>Dp</var> (optional) specifies either that the item has from 0 to 15 decimal places as specified by <var class="term">k</var>, or that the number of decimal places is variable.   
<ul>
<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><var>Dp <i>k</i></var> 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>   
<li>If <code>Dp *</code> is specified, all decimal places in the item are retained. If this option is omitted, the default is zero. Do not use <var>Dp</var>, if the value to be moved to the item contains a decimal point. </li>   
</ul></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.  
<li><var>Pad</var> (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 <var>Pad</var> 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>
<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>
The pad character can be a single quoted character, a hexadecimal value expressed as <code>X'hh'</code>, or a decimal number. The hexadecimal or decimal value can be from 0 to 255. </p></li>
</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><var>Strip</var>, the default, specifies to remove the pad characters, if an item value is extracted from an image. <var>NoStrip</var> 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><var>Justify</var> (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 <var>Justify</var> 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><var>Initial</var> (optional) defines the value placed in the item by a <var>Prepare</var> statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If an <var>Initial</var> clause is omitted, <var>Blank</var> is the default initial value. </li>
</li>
</ul>
</ul>
   
   
====AFTER and AT clauses====
====After and At clauses====
<ul>
<ul>
<li>The AFTER and AT clauses are optional and mutually exclusive. Their function is as follows:
<li>The <var>After</var> and <var>At</var> clauses are optional and mutually exclusive. Their function is as follows:
<p>
<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>
An <var>After</var> 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>
<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>
An <var>At</var> clause defines the location of the item in the image as adjacent to an item or array, or it redefines the space defined by a previously defined item. If the location is not adjacent in a forward direction to the previous item definition, a <var>Skip</var> is implied (see [[#Default Skip statement|Default Skip statement]]). </p>
<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>
If position is used, the location is relative to the beginning of the image.
The position option can have a value from 1 through 32767. </p>
<p>
<p>
Consider the following restrictions when using an AFTER or AT clause:</p>
An item or array named in the <var>At</var> clause cannot have a <var>Depending On</var> option. </p>
<p>
Consider the following restrictions when using an <var>After</var> or <var>At</var> clause:</p>
<ul>
<ul>
<li>Outside of an array definition, the AFTER or AT clause cannot name an item inside the array.</li>
<li>Outside of an array definition, the <var>After</var> or <var>At</var> 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>Within an array definition, the <var>After</var> or <var>At</var> 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>
<li>If neither <var>After</var> nor <var>At</var> is specified, the item abuts the end of the preceding item or the start of the image. </li>
</ul>
</ul></li>
</li>
</ul>
</ul>
   
   
====OCCURS clause====
====Occurs clause====
<ul>
<ul>
<li>The OCCURS clause (optional) specifies that there are multiple occurrences of the item. The OCCURS clause options are as follows:  
<li>The <var>Occurs</var> clause (optional) specifies that there are multiple occurrences of the item. The <var>Occurs</var> clause options are as follows:  
<ul>
<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><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 <var>Prepare</var> 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>The <var>Depending On</var> 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 <var>Unknown</var>, cannot be an array element, and cannot be positioned in the image following an item defined with <var>Len Unknown</var> or an array defined with <var>Occurs Unknown</var>. </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>
<li><var>Unknown</var> specifies that the number of occurrences of the item is determined by the SOUL request and that the <var>Identify</var> statement establishes the number of occurrences. </li>
</ul>
</ul>
</li></ul>
</li></ul>
   
   
==Defining a binary item==
===Defining a binary item===
   
   
====Syntax====
====Syntax====
<p>
<p>
Define binary items with this syntax:   </p>
Define binary items with this syntax:
<p class="syntax">BINARY {LEN {<span class="term">n</span> | UNKNOWN} | BITS <span class="term">n</span> | TO <span class="term">position</span>}  
</p>
  [BP <span class="term">n</span>]  
<p class="syntax">Binary {Len {<span class="term">n</span> | Unknown} | Bits <span class="term">n</span> | To <span class="term">position</span>}  
  [SIGNED | UNSIGNED] [ALIGN]  
  [Bp <span class="term">n</span>]  
  [INITIAL {NULL | <span class="term">number</span> | BLANK | ZERO}]  
  [Signed | Unsigned] [Align]  
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>}  
  [Initial {Null | <span class="term">number</span> | Blank | Zero}]  
  | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}]  
  [After {<span class="term">itemname</span> | <span class="term">arrayname</span>}  
  [OCCURS {<span class="term">n</span> [DEPENDING ON {<span class="term">itemname</span> | <span class="term">%variable</span>}]  
  | At {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}]  
  | UNKNOWN}]
  [Occurs {<span class="term">n</span> [Depending On {<span class="term">itemname</span> | <span class="term">%variable</span>}]  
  | Unknown}]
</p>
</p>
Where:
Where:
<ul>
<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><var>Len</var> specifies the length as 1-4 bytes, or as <var>Unknown</var> if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li>
   
   
<li>BITS specifies the length as 8, 16, 24, or 32 bits. </li>
<li><var>Bits</var> 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><var>To</var> specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (<var>To</var>) position of the item is required unless provided in a <var>Default</var> 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><var>Bp</var> (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 <var>Bp</var> 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.   
<li><var>Signed</var>, optional and the default, specifies that a negative number can be stored in the item in two's complement form. <var>Unsigned</var>, optional, specifies that the item is always positive and that the leftmost bit is part of the number.   
<p class="note"><b>Note:</b>
<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>
If a negative number is read into an <var>Unsigned Binary</var> 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:  
<li><var>Align</var>, optional, specifies that the item is aligned as follows:  
<ul>
<ul>
<li>BINARY LEN 2 on a halfword boundary</li>
<li><code>Binary Len 2</code> on a halfword boundary </li>
<li>BINARY LEN 4 on a fullword boundary </li>
<li><code>Binary Len 4</code> on a fullword boundary </li>
<li>The ALIGN option is ignored for 1- and 3-byte BINARY items.</li>
</ul>
</ul>
<p>
<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>
The <var>Align</var> option is ignored for 1- and 3-byte <var>Binary</var> items. </p>
<p>
The item is aligned by inserting a <var>Skip</var> statement preceding the item so that the item's location is on the correct boundary. In arrays, a <var>Skip</var> is inserted at the end of each occurrence of the array and of any parent array to make the length of each occurrence a multiple of the largest aligned item in the array. </p>
<p>
<p>
The ALIGN option cannot be specified for an item:</p>
The <var>Align</var>option cannot be specified for an item:</p>
<ul>
<ul>
<li>When length is defined as UNKNOWN. </li>
<li>When length is defined as <var>Unknown</var>. </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>
<li>When location is unknown during compilation because a previously defined item specified <var>Len Unknown</var> or <var>Occurs Unknown</var>. </li>
 
<li>Containing an <var>At</var> clause that specifies a location that is not already aligned on the proper storage boundary. </li>
</ul></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><var>Initial</var> (optional) defines the value placed in the item by a <var>Prepare</var> 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, <var>Null</var> 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 <var>After</var> and <var>At</var> clauses are mutually exclusive; they 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>The optional <var>Occurs</var> clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>
</li>
</ul>
</ul>
   
   
==Defining a packed decimal item==
===Defining a packed decimal item===
   
   
====Syntax====
====Syntax====
<p>
<p>
Define packed decimal items with this 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>}  
<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>]  
  [Dp <span class="term">n</span>]  
  [SIGNED | UNSIGNED]  
  [Signed | Unsigned]  
  [INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}]  
  [Initial {Zero | <span class="term">number</span> | Blank | Null}]  
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</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>}]  
  | 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>}]
  [Occurs {<span class="term">n</span> [Depending On {<span class="term">itemname</span> | <span class="term">%variable</span>}]
  | UNKNOWN}]
  | Unknown}]
</p>
</p>
Where:
Where:
<ul>
<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><var>Len</var> specifies the length as 1-8 bytes or as <var>Unknown</var> if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li>
   
   
<li>DIGITS specifies the length as 1-15 decimal digits. </li>
<li><var>Digits</var> 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><var>To</var> 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 <var>Default</var> 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><var>Dp</var> (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><var>Signed</var>, 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><var>Unsigned</var> (optional) specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal <code>F</code>. </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><var>Initial</var> (optional) defines the value placed in the item by a <var>Prepare</var> 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 mutually exclusive and optional <var>After</var> and <var>At</var> 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>The optional <var>Occurs</var> clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>
</li>
</ul>
</ul>
   
   
==Defining a zoned decimal item==
===Defining a zoned decimal item===
   
   
====Syntax====
====Syntax====
<p>
<p>
Define zoned decimal items with this syntax:   </p>
Define zoned decimal items with this syntax:  
<p class="syntax">ZONED {LEN {<span class="term">n</span> | UNKNOWN} | DIGITS <span class="term">n</span> | TO <span class="term">position</span>}  
</p>
  [DP <span class="term">n</span>]  
<p class="syntax">Zoned {Len {<span class="term">n</span> | Unknown} | Digits <span class="term">n</span> | To <span class="term">position</span>}  
  [SIGNED | UNSIGNED]  
  [Dp <span class="term">n</span>]  
  [INITIAL {ZERO | <span class="term">number</span> | BLANK | NULL}]  
  [Signed | Unsigned]  
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>}  
  [Initial {Zero | <span class="term">number</span> | Blank | Null}]  
  | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}]  
  [After {<span class="term">itemname</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}]
  | 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>
</p>
Where:
Where:
<ul>
<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><var>Len</var> specifies the length as 1-15 bytes, or as <var>Unknown</var> if the length is determined by the request and the <var>Identify</var> statement establishes the length. </li>
   
   
<li>DIGITS specifies the length as 1-15 decimal digits. </li>
<li><var>Digits</var> 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><var>To</var> specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (<var>To</var>) position of the item is required unless provided in a <var>Default</var> 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><var>Dp</var>, 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 <var class="term">n</var> 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><var>Signed</var>, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal <code>C</code> for a positive number, and it is <code>D</code> 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><var>Unsigned</var>, optional, specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal <code>F</code>. </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><var>Initial</var>, optional, defines the value placed in the item by a <var>Prepare</var> 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 mutually exclusive and optional <var>After</var> and <var>At</var> 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>The optional <var>Occurs</var> clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>
</li>
</ul>
</ul>
   
   
==Defining a floating point item==
===Defining a floating point item===
   
   
====Syntax====
====Syntax====
<p class="syntax">FLOAT {LEN {<span class="term">n</span> | UNKNOWN} TO <span class="term">position</span>  
<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]
  [Initial {Zero | <span class="term">number</span> | Blank | Null}] [Align]
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</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>}]  
  | 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}]
  [Occurs {<span class="term">n</span> [Depending On {<span class="term">itemname</span> | <span class="term">%variable</span>}] | Unknown}]
</p>
</p>
Where:
Where:
<ul>
<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.  
<li><var>Len</var> specifies the length as 4, 8, or 16 bytes, or as <var>Unknown</var> if the length is determined by the request and the <var>Identify</var> statement establishes the length.  
<p>
<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>
Although you can move 16-byte floating-point values between data sets and files, intermediate results and %variables inside SOUL are 8 bytes long. </p>
<p>
<p>
Arithmetic manipulations and data conversions retain only 15 significant decimal digits in 8 bytes.</p>
Arithmetic manipulations and data conversions retain only 15 significant decimal digits in 8 bytes. </p></li>
</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><var>To</var> specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (<var>To</var>) position of the item is required unless provided in a <var>Default</var> 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><var>Initial</var>, optional, defines the value placed in the item by a <var>Prepare</var> 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:   
<li><var>Align</var>, optional, specifies that the item is aligned as follows:   
<ul>
<ul>
<li>FLOAT LEN 4 on a fullword boundary</li>
<li><code>Float Len 4</code> on a fullword boundary </li>
<li>FLOAT LEN 8 on a doubleword boundary</li>
<li><code>Float Len 8</code> on a doubleword boundary </li>
<li>FLOAT LEN 16 on a doubleword boundary </li>
<li><code>Float Len 16</code> 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>
</ul>
<p>
<p>
The ALIGN option cannot be specified for an item: </p>
The item is aligned by inserting a <var>Skip</var> statement preceding the item so that the item's location is on the correct boundary. In arrays, a <var>Skip</var> 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. </p>
<p>
The <var>Align</var> option cannot be specified for an item: </p>
<ul>
<ul>
<li>When length is defined a UNKNOWN.</li>
<li>When length is defined as <var>Unknown</var>. </li>
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN.  </li>
<li>When location is unknown during compilation because a previously defined item specified <var>Len Unknown</var> or <var>Occurs Unknown</var>.  </li>
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary. </li>
<li>Containing an <var>At</var> clause that specifies a location that is not already aligned on the proper storage boundary. </li>
</ul></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 optional <var>After</var> and <var>At</var> clauses are mutually exclusive; they 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>The optional <var>Occurs</var> clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>
</li>
</ul>
</ul>
   
   
==Defining an exponential notation item==
===Defining an exponential notation item===
   
   
====Syntax====
====Syntax====
<p>
<p>
Define exponential notation items with this syntax:   </p>
Define exponential notation items with this syntax:  
<p class="syntax">EFORMAT {LEN {<span class="term">n</span> | UNKNOWN} | TO <span class="term">position</span>}  
</p>
  [PAD {BLANK | <span class="term">character</span> | NULL}]  
<p class="syntax">Eformat {Len {<span class="term">n</span> | Unknown} | To <span class="term">position</span>}  
  [STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}]  
  [Pad {Blank | <span class="term">character</span> | Null}]  
  [INITIAL {BLANK | <span class="term">string</span> | ZERO | NULL}] [DIGITS <span class="term">n</span>]  
  [Strip | NoStrip] [Justify {Left | Right}]  
  [DP <span class="term">n</span>] [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>}
  [Initial {Blank | <span class="term">string</span> | Zero | Null}] [Digits <span class="term">n</span>]  
  | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</span>}]
  [Dp <span class="term">n</span>] [After {<span class="term">itemname</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}]
  | 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>
</p>
Where:
Where:
<ul>
<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><var>Len</var> specifies the length either as 1-255 bytes, or as <var>Unknown</var> if the length is determined by the request and the <var>Identify</var> 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><var>To</var> specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (<var>To</var>) position of the item is required unless provided in a <var>Default</var> 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><var>Pad</var>, 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 <code>X'<i>hh</i>'</code>, 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><var>Strip</var>, the default, specifies that the pad character is removed if an item value is extracted from an image. <var>NoStrip</var> 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><var>Justify</var>, 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><var>Initial</var>, optional, defines the value placed in the item by a <var>Prepare</var> 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><var>Digits</var> 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><var>Dp</var> 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 mutually exclusive and optional <var>After</var> and <var>At</var> 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>The optional <var>Occurs</var> clause specifies that there are multiple occurrences of the item. See [[#Defining a string item|Defining a string item]] for a complete discussion. </li>
</li>
</ul>
</ul>
   
   
==Item definition examples==
===Item definition examples===
   
   
===An image containing various item types===
====An image containing various item types====
<p class="code">IMAGE GENERAL.LEDGER.RECORD
<p class="code">IMAGE GENERAL.LEDGER.RECORD
       GL.RECORD.TYPE      IS STRING LEN 1
       GL.RECORD.TYPE      IS STRING LEN 1
Line 748: Line 767:
</p>
</p>
   
   
===Using the AT and AFTER clauses===
====Using the At and After clauses====
<p class="code">IMAGE PRINT.DATA
<p class="code">IMAGE PRINT.DATA
PRINT.LINE1  IS STRING LEN 133 DP *
PRINT.LINE1  IS STRING LEN 133 DP *
Line 763: Line 782:
</p>
</p>
<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>
In the preceding example, <code>PRINT.LINE2</code> is placed adjacent to the end of <code>PRINT.LINE1</code>. Without the <var>After</var> clause, an <var>At</var> clause would be required to specify the numeric position of <code>PRINT.LINE2</code> in the image. </p>
 
==Defining arrays==
==Defining arrays==
<p>
<p>
An <var class="term">array</var> contains multiple occurrences of a single item or a group of items. </p>
An <b>array</b> contains multiple occurrences of a single item or a group of items. </p>
   
   
===Array definition statements===
===Array definition statements===
<p>
<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>
When an array is a single item, the array can be defined by using the <var>Occurs</var> clause on the item definition or an <var>Array</var> statement. </p>
<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>
When an array contains more than one item, the array is defined by using an <var>Array</var> statement, and it is followed by definitions of the items that compose each element of the array. </p>
<p>
<p>
None of the items in an array or subordinate array can specify LEN UNKNOWN or OCCURS UNKNOWN.</p>
None of the items in an array or subordinate array can specify <var>Len Unknown</var> or <var>Occurs Unknown</var>. </p>
   
   
===Types of arrays===
===Types of arrays===
<p>
<p>
The format of the ARRAY statement depends on which of the following types of arrays is being defined:</p>
The format of the <var>Array</var> statement depends on which of the following types of arrays is being defined: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 795: Line 814:
<tr>
<tr>
<td>Unknown </td>
<td>Unknown </td>
<td>Not known. The maximum number of occurrences must be specified during evaluation by using the [[#IDENTIFY statement|IDENTIFY statement]]. </td>
<td>Not known. The maximum number of occurrences must be specified during evaluation by using the [[#Identify statement|Identify statement]]. </td>
</tr>
</tr>
</table>
</table>
   
   
===ARRAY and END ARRAY statements===
===Array and End Array statements===
<p>
<p>
You define an array with an ARRAY statement. The definitions of items and subordinate arrays follow the ARRAY statement. </p>
You define an array with an <var>Array</var> statement. The definitions of items and subordinate arrays follow the <var>Array</var> statement. </p>
<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>
You specify the end of the array with an <var>End Array</var> statement. <var>End Array</var> ends the definition of the array defined by the preceding <var>Array</var> statement. In addition, an <var>Image</var> or <var>End Image</var> statement ends all preceding <var>Array</var> definitions. </p>
   
   
==Defining a fixed occurrence array==
===Defining a fixed occurrence array===
<p>
<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>
A <b>fixed occurrence array</b> 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====
====Syntax====
<p>
<p>
The format of the ARRAY statement used to define a fixed occurrence array is:</p>
The format of the <var>Array</var> statement used to define a fixed occurrence array is:
<p class="syntax">ARRAY [<span class="term">arrayname</span>] OCCURS <span class="term">n</span>  
</p>
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</span>}  
<p class="syntax">Array [<span class="term">arrayname</span>] Occurs <span class="term">n</span>  
  | AT {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imagname1</span> | <span class="term">arrayname</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>
</p>
Where:
Where:
<ul>
<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">arrayname</var> (optional) names the array. An array must be named if it is specified in the <var>At</var> clause of an image definition or in the <var>After</var> or <var>At</var> 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><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><var>After</var> and <var>At</var> 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>
</li>
</ul>
</ul>


====Example====
====Example====
<p>
<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>
The following example of an image contains a fixed occurrence array. In this example, each element of the <code>SALES.MONTHLY</code> array contains the item <code>SALES.TOTAL</code> and five occurrences of the item <code>SALES.BY.MODEL</code>.
</p>
<p class="code">IMAGE SALES
<p class="code">IMAGE SALES
       ARRAY SALES.MONTHLY OCCURS 12
       ARRAY SALES.MONTHLY OCCURS 12
Line 849: Line 869:
</p>
</p>
   
   
==Defining a depending array==
===Defining a depending array===
<p>
<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>
A <b>depending array</b> 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===
====Depending variable====
<p>
<p>
A depending variable is used to specify the actual number of occurrences that exist in the record.   </p>
A depending variable is used to specify the actual number of occurrences that exist in the record. </p>
<p>
<p>
The depending variable is used in this manner:</p>
The depending variable is used in this manner:</p>
<ul>
<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 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 <var>Prepare Image</var> 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>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.   
Line 869: Line 889:
====Restrictions====
====Restrictions====
<p>
<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>
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 <var>After</var> or <var>At</var> clause are mutually exclusive. </p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The form of the ARRAY statement used for defining a depending array is:</p>
The form of the <var>Array</var> statement used for defining a depending array is:
<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>
<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>
</p>
Where:
Where:
<ul>
<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">arrayname</var>, optional, names the array. An array must be named if it is specified in the <var>At</var> clause of an image definition or in the <var>After</var> or <var>At</var> 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><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:  
<li>The <var>Depending On</var> 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>
<ul>
<li>Be an array element</li>
<li>Be an array element</li>
<li>Vary in length, that is, be defined with LEN UNKNOWN</li>
<li>Vary in length, that is, be defined with <var>Len Unknown</var></li>
<li>Follow any varying length item or array in the image.   </li>
<li>Follow any varying length item or array in the image. </li>
</ul></li>
</ul></li>
</ul>
</ul>
Line 892: Line 913:
====Example====
====Example====
<p>
<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>
The following example of an image contains an array with a depending variable is shown below. In this example, <code>SALES.MODELS</code> contains 15 occurrences of the item <code>SALES.MODEL.NO</code>. Therefore, the external record can contain from 0 to 15 occurrences.
</p>
<p class="code">IMAGE SALES
<p class="code">IMAGE SALES
       SALES.MODELS            IS BINARY LEN 2
       SALES.MODELS            IS BINARY LEN 2
Line 901: Line 923:
</p>
</p>
<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>
If a record is read into the previous image, the number of items defined by the value of the item <code>SALES.MODELS</code> are moved from the record into the array. Any occurrences of <code>SALES.MODEL.NO</code> not filled in the array from the record are initialized to zero. Before a record is written from the <code>SALES</code> image to a sequential file or terminal, the number of items defined by the value of the item <code>SALES.MODELS</code> 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==
===Defining an unknown array===
<p>
<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>
An array must be defined as <b>unknown</b> 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 <var>Unknown</var>. During evaluation, the <var>Identify</var> statement is used to specify the number of occurrences in the array before any item in the array is referred to. </p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The format of the ARRAY statement used for defining an unknown array is:</p>
The format of the <var>Array</var> statement used for defining an unknown array is: </p>
<p class="syntax">ARRAY [<span class="term">arrayname</span>] OCCURS UNKNOWN
<p class="syntax">Array [<span class="term">arrayname</span>] Occurs Unknown
  [AFTER {<span class="term">itemname</span> | <span class="term">arrayname</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">imaginename1</span>  
  | At {<span class="term">position</span> | <span class="term">itemname</span> | <span class="term">imaginename1</span> | <span class="term">arrayname</span>}]
| <span class="term">arrayname</span>}]
</p>
</p>
Where:
Where:
<ul>
<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><var class="term">arrayname</var> is required and names the array. This name is used to identify the array in <var>Identify</var> 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>The <var>After</var> and <var>At</var> 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>
</li>
</ul>
</ul>
Line 925: Line 946:
====Example====
====Example====
<p>
<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>
This example illustrates the use of unknown arrays. In this example, the number of occurrences of the array <code>TRANSACTION</code> is contained in the item <code>TRANS.COUNT</code>. Before the items <code>TRANS.NO</code>, <code>TRANS.AMT</code>, or <code>TRANS.CUST</code> can be referred to, the <var>Identify</var> statement is executed to set the number of occurrences.
</p>
<p class="code">TRANS.COUNT        IS BINARY LEN 4
<p class="code">TRANS.COUNT        IS BINARY LEN 4
ARRAY TRANSACTION OCCURS UNKNOWN
ARRAY TRANSACTION OCCURS UNKNOWN
Line 936: Line 958:
==Referring to array elements==
==Referring to array elements==
<p>
<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>
Individual items within an array are identified by <b>subscripts</b>. A subscript is enclosed in parentheses and can be any expression that evaluates to a number from 1 to the maximum size of the array.  </p>
   
   
===Nested arrays===
===Nested arrays===
<p>
<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>
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====
====Example====
<p>
<p>
In this example, the fifth student in the second course would be referred to as COURSE.STUDENT(2,5).</p>
In this example, the fifth student in the second course would be referred to as <code>COURSE.STUDENT(2,5)</code>.
</p>
<p class="code">IMAGE COURSE.DATA
<p class="code">IMAGE COURSE.DATA
       ARRAY OCCURS 20
       ARRAY OCCURS 20
Line 950: Line 973:
         COURSE.NAME        IS STRING LEN 25
         COURSE.NAME        IS STRING LEN 25
         COURSE.INSTRUCTOR  IS STRING LEN 20
         COURSE.INSTRUCTOR  IS STRING LEN 20
        COURSE.STUDENT    IS STRING LEN 20 OCCURS 30
        COURSE.STUDENT    IS STRING LEN 20 OCCURS 30
       END ARRAY
       END ARRAY
END IMAGE
END IMAGE
Line 957: Line 980:
==Initialization of array values==
==Initialization of array values==
<p>
<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>
<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 (<tt>*</tt>) as the subscript value. Using the asterisk is valid for percent variable arrays and image arrays. </p>
   
   
====Example 1====
====Example 1====
Line 978: Line 1,001:
====Example 3====
====Example 3====
<p>
<p>
The following example prints AAA and 100:</p>
The following example prints <code>AAA</code> and <code>100</code>:
</p>
<p class="code">BEGIN
<p class="code">BEGIN
  IMAGE TEST
  IMAGE TEST
Line 998: Line 1,022:
====Example 4====
====Example 4====
<p>
<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>
The asterisk is not valid on the right side of a SOUL assignment statement. The following statement is invalid and causes a compilation error:</p>
<p class="code">%X = %ARRAY.ITEM(*,*,*)
<p class="code">%X = %ARRAY.ITEM(*,*,*)
</p>
</p>
Line 1,006: Line 1,030:
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>
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>
<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>
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>
<p>
With a Large Object field, you can directly address each item using the <offset>,<length> syntax available for Large Object fields.</p>
With a Large Object field, you can directly address each item using the <var class="term">offset,length</var> syntax available for Large Object fields.</p>
<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>
There is one Table B access to retrieve the Large Object descriptor, and one Table&nbsp;E access to read the page that your data resides on, no matter how far into the object the data resides.</p>
<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>
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>
Line 1,020: Line 1,044:
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>
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>
<p>
Space is reserved automatically by an AT clause that places an item beyond the end of the last defined item.     </p>
Space is reserved automatically by an <var>At</var> clause that places an item beyond the end of the last defined item. </p>
   
   
===SKIP statement===
===Skip statement===
<p>
<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>
Space is reserved explicitly by using the <var>Skip</var> statement. The space reserved by a <var>Skip</var> statement can be initialized by a <var>Prepare</var> statement but cannot be accessed. </p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The format of the SKIP statement for reserving space is:</p>
The format of the <var>Skip</var> statement for reserving space is:
<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>
</p>
{{Template:Skip Position statement syntax}}
Where:
Where:
<ul>
<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>The <var><i>itemname</i> Is</var> clause (optional) names a reserved area that can be referred to by an <var>After</var> or <var>At</var> 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><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:
<li>The <var>Initial</var> clause indicates the character with which the area is filled by <var>Prepare</var> and <var>Identify</var> statements. Options are as follows:
<ul>
<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>character &mdash; a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as <code>X'hh'</code></li>
<li>BLANK &mdash; white spaces</li>
 
<li>NULL &mdash; binary zeros </li>
<li><var>Blank</var> &mdash; white spaces</li>
 
<li><var>Null</var> &mdash; binary zeros </li>
</ul>
</ul>
<p>
<p>
If the INITIAL clause is omitted, NULL is the default.  </p>
If the <var>Initial</var> clause is omitted, <var>Null</var> is the default.  </p></li>
</li>
</ul>
</ul>
   
   
====Example====
====Example====
<p>
<p>
This sample SKIP statement reserves two bytes before the next image item: </p>
This sample <var>Skip</var> statement reserves two bytes before the next image item: </p>
<p class="code">SKIP 2 POSITIONS
<p class="code">SKIP 2 POSITIONS
</p>
</p>
 
==DEFAULT TYPE and DEFAULT SKIP statements==
==Default Type and Default Skip statements==
<p>
<p>
You can provide default values for image item options to eliminate repetition of these options on each item definition, using:     </p>
You can provide default values for image item options to eliminate repetition of these options on each item definition, using: </p>
<ul>
<ul>
<li>DEFAULT TYPE</li>
<li><var>Default Type</var></li>
<li>DEFAULT SKIP </li>
<li><var>Default Skip</var> </li>
</ul>
</ul>
   
   
===DEFAULT TYPE statement===
===Default Type statement===
<p>
<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>
The <var>Default Type</var> statement lets you set default option values for each item type. The options specified on a <var>Default Type</var> 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====
====Syntax====
<p>
<p>
The format of the DEFAULT TYPE statement is:</p>
The format of the <var>Default Type</var> statement is:</p>
<p class="syntax">DEFAULT [TYPE] <span class="term">type</span> <span class="term">options</span>
<p class="syntax">Default [Type] <span class="term">type</span> <span class="term">options</span>
</p>
</p>
Where:
Where:
<ul>
<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>The optional <var>Type</var> keyword specifies a default data type for any item definition that does not explicitly define the data type. Without the <var>Type</var> 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">type</var> specifies the data type of the item. Valid values are <var>String</var>, <var>Binary</var>, <var>Float</var>, <var>Packed</var>, <var>Zoned</var>, or <var>EFormat</var>.</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><var class="term">options</var> specifies any of the options that are valid for the item type except for the <var>To</var>, <var>After</var>, <var>At</var>, and <var>Occurs</var> clauses. </li>
</li>
</ul>
</ul>
   
   
===DEFAULT SKIP statement===
===Default Skip statement===
<p>
<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>
The <var>Default Skip</var> statement specifies the default length or initial value for a <var>Skip</var> statement or an implied skip. It can appear anywhere in an image definition and remains in effect until the next <var>Default Skip</var> statement.</p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The format of the DEFAULT SKIP statement is:</p>
The format of the <var>Default Skip</var> statement is:</p>
<p class="syntax">DEFAULT SKIP <span class="term">n</span> POSITION[S]  
<p class="syntax">Default Skip <span class="term">n</span> Position[s]  
   [INITIAL {NULL | '<span class="term">character</span>' | BLANK}]
   [Initial {Null | '<span class="term">character</span>' | Blank}]
</p>
</p>
Where:
Where:
Line 1,096: Line 1,119:
<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><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:  
<li>The <var>Initial</var> clause indicates the fill character for <var>Prepare</var> and <var>Identify</var> statements. Options are as follows:  
<ul>
<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><var>Null</var> &mdash; binary zeros </li>
<li>BLANK &mdash; white space</li>
 
<li>NULL &mdash; binary zeros </li>
<li><var class="term">character</var> &mdash; a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as <code>X'hh'</code> </li>
 
<li><var>Blank</var> &mdash; white space </li>
</ul>
</ul>
<p>
<p>
If the INITIAL clause is omitted, NULL is the default. </p>
If the <var>Initial</var> clause is omitted, <var>Null</var> is the default. </p></li>
</li>
</ul>
</ul>
   
   
===Example of DEFAULT statements===
===Example of Default statements===
<p>
<p>
The following examples show how an image can be described without and then with DEFAULT statements.</p>
The following examples show how an image can be described without and then with <var>Default</var> statements.</p>
   
   
====Without DEFAULT statements====
====Without Default statements====
<p class="code">IMAGE SALES
<p class="code">IMAGE SALES
       SALES.YEAR.TOTAL    IS PACKED DIGITS 7 DP 2
       SALES.YEAR.TOTAL    IS PACKED DIGITS 7 DP 2
Line 1,122: Line 1,146:
</p>
</p>
   
   
====With DEFAULT statements====
====With Default statements====
<p class="code">IMAGE SALES
<p class="code">IMAGE SALES
  DEFAULT TYPE STRING LEN 20
  DEFAULT TYPE STRING LEN 20
Line 1,155: Line 1,179:


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


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


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


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


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


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


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


<tr>
<tr>
<td>WRITE IMAGE</td>
<td><var>Write Image</var></td>
<td>Writes a record to a sequential file or to a terminal.</td>
<td>Writes a record to a sequential file or to a terminal.</td>
</tr>
</tr>
Line 1,197: Line 1,221:
===Key field for VSAM files===
===Key field for VSAM files===
<p>
<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>
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 <var>Read Image</var> and <var>Position</var> statements attempt to convert the numeric value to string.</p>
<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>
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 <var>Read</var> or <var>Position</var> statement. </p>
<p>
<p>
An example of this technique for a VSAM file that has a 4-byte binary key is illustrated below:</p>
An example of this technique for a VSAM file that has a 4-byte binary key is illustrated below:</p>
Line 1,210: Line 1,234:
END IMAGE
END IMAGE
OPEN DATASET VSAMFILE
OPEN DATASET VSAMFILE
     IF $STATUS NE 0 THEN
     IF $Status NE 0 THEN
         PRINT $ERRMSG
         PRINT $Errmsg
         STOP
         STOP
     END IF
     END IF
Line 1,222: Line 1,246:
         .
         .
</p>
</p>
 
==Close statement==
==Close statement==
<p>
<p>
Line 1,229: Line 1,253:
====Syntax====
====Syntax====
<p>
<p>
The format of the <var>Close</var> statement is:</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="term">ext-filename</span> | <span class="term">%variable</span>}
{{Template:Close statement (external I/O) syntax}}
| <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:
Where:
<ul>
<ul>
<li>You must specify either the <var>Dataset</var>, <var>External</var>, or <var>Terminal</var> keyword.</li>
<li>You must specify 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><var>Dataset</var> 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>External</var> 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 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><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 <code>Terminal</code>.  </li>
</li>
</ul>
</ul>
 
===Closing a Model 204 file===
===Closing a Model 204 file===
<p>
<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>
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">SOUL</var> request, or the <var>[[CLOSE command|CLOSE]]</var> command outside a request.</p>
   
   
==IDENTIFY statement==
==Identify statement==
<p>
<p>
The IDENTIFY statement establishes: </p>
The <var>Identify</var> statement establishes: </p>
<ul>
<ul>
<li>Active image, if multiple images define the same block.</li>
<li>Active image, if multiple images define the same block.</li>
<li>Length of items that were defined as UNKNOWN.</li>
<li>Length of items that were defined as <var>Unknown</var>.</li>
<li>Number of occurrences for arrays that were defined as UNKNOWN. </li>
<li>Number of occurrences for arrays that were defined as <var>Unknown</var>. </li>
</ul>
</ul>
   
   
====Syntax====
====Syntax====
<p>
<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>
The complete syntax for the <var>Identify</var> statement follows. The form of the <var>Identify</var> statement used to perform each of these activities is then discussed in detail.
<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>
</p>
{{Template:Identify statement syntax}}
Where:
Where:
<ul>
<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> 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><var class="term">%imagename</var>:<var class="term">itemname</var> is an item that was defined with <var>Len Unknown</var> or <var>Occurs Unknown</var>. </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>The <var>Len</var> 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><var class="term">%imagename</var>:<var class="term">arrayname</var> is an array that was defined with <var>Occurs Unknown</var>.</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>The <var>Occurs</var> clause specifies the number of occurrences of the item or a %variable that contains the number. The number of occurrences cannot exceed 32767. </li>
</li>
</ul>
</ul>
 
===Establishing an active image===
===Establishing an active image===
<p>
<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>
Use the following form of the <var>Identify</var> statement to switch the active image to the named image, when multiple images define the same block:</p>
<p class="syntax">IDENTIFY [IMAGE] <span class="term">imagename</span>
<p class="syntax">Identify [Image] <span class="term">imagename</span>
</p>
</p>
<p>
<p>
The IDENTIFY statement also initializes the items, if any, that were not initialized by a previous READ IMAGE or PREPARE statement. </p>
The <var>Identify</var> statement also initializes the items, if any, that were not initialized by a previous <var>Read Image</var> or <var>Prepare</var> statement.  
<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>
</p>
<p class="note"><b>Note:</b> Use the <var>Identify</var> statement instead of a <var>Prepare</var> statement for requests in which you want to maintain data passed in an image.</p>
   
   
====Use with global images====
====Use with global images====
<p>
<p>
When used with global images, the IDENTIFY IMAGE statement, can cause request termination due to either: </p>
When used with global images, the <var>Identify Image</var> statement can cause request termination due to either of these: </p>
<ul>
<ul>
<li>Definition mismatches. See [[Global features#Consistency checks performed|Consistency checks performed]] for a description.</li>
<li>Definition mismatches. See [[Global features#Consistency checks performed|Consistency checks performed]] for a description. </li>
   
   
<li>Insufficient space in GTBL. See the
<li>Insufficient space in [[Defining the runtime environment (CCAIN)#Understanding the global variable table (GTBL)|GTBL]]. </li>
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]</var>.  
</li>
</ul>
</ul>
<p>
<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>
The <var>Identify Image</var> statement does not refresh a global image, if a copy of that image is already in GTBL. The <var>Identify Image</var> 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===
===Establishing lengths for Unknown items===
<p>
<p>
Use the following form of the IDENTIFY statement to set the length for items defined with LEN UNKNOWN:</p>
Use the following form of the <var>Identify</var> statement to set the length for items defined with <var>Len Unknown</var>:
<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 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>
<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>
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 <var>Identify</var> statement. If you must enlarge an array after the length is established, copy the image (using assignment statements) to another image where the array is larger.</p>
   
   
===Establishing occurrences for UNKNOWN arrays===
===Establishing occurrences for Unknown arrays===
<p>
<p>
Use the following form of the IDENTIFY statement to set the number of occurrences for arrays or items defined with OCCURS UNKNOWN:</p>
Use the following form of the <var>Identify</var> statement to set the number of occurrences for arrays or items defined with <var>Occurs Unknown</var>:
<p class="syntax">IDENTIFY {<span class="term">%imagename</span>:<span class="term">arrayname</span>  
</p>
  | <span class="term">%imagename</span>:<span class="term">itemname</span>} OCCURS {<span class="term">n</span> | <span class="term">%variable</span>}
<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>
<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>
You cannot change the number of occurrences after they are defined by an <var>Identify</var> statement. If you issue an <var>Identify</var> statement for an item whose length was previously set by an <var>Identify</var> statement, the request is cancelled. </p>
<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>
You must issue a <var>Prepare</var> statement before another <var>Identify</var> statement can be issued on the same item. If you need to enlarge an array after the number of occurrences is established, you must copy the image (using assignment) to another image where the array is larger. </p>
 
==MODIFY BUFFER statement==
==Modify Buffer statement==
   
   
====Function====
====Function====
Line 1,331: Line 1,348:
   
   
====Syntax====
====Syntax====
<p class="syntax">MODIFY BUFFER [SIZE=<span class="term">n</span> | <span class="term">%variable</span> [PRESERVE | NOPRESERVE]]  
<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]
   [Fill [X'<span class="term">nn</span>' | C'<span class="term">x</span>'] | CLEAR]
</p>
</p>
Where:
Where:
<ul>
<ul>
<li>BUFFER (formerly and still accepted as MQ_BUFFER) specifies the Universal Buffer area. </li>
<li><var>Buffer</var> (formerly and still accepted as <code>MQ_BUFFER</code>) 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><var>Size</var> specifies the number of bytes allocated for the <var>Buffer</var> area. If the value of the <var>Size</var> 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).   
<li><var>Preserve</var> specifies to retain the buffer contents. If a storage allocation error occurs, the value of 8 is set in the <var>$Status</var> return code (which is the standard WebSphere MQ value for this error).   
<p>
<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>
If the data was truncated when the buffer was shrunk, then the value of 14 for data truncation is set in <var>$Status</var>, although the operation succeeds. </p>
</li>
</li>


<li>CLEAR option, the default, specifies to overwrite the buffer with X'00'.</li>
<li><var>Clear</var> 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.
<li><var>Fill</var> option specifies a fill-character to use; for example, X'40' fills with blanks. The <var>Fill</var> option can also be a decimal number and/or the equals sign (<tt>=</tt>), or it can be an alpha character (<var>C</var>) and/or the equals sign. If a value is not specified after the keyword <var>Fill</var>, the default value is the <var>Clear</var> option.
<p>
<p>
If the FILL or CLEAR option is specified, the behavior of MODIFY BUFFER statement depends on what other options are used:</p>
If the <var>Fill</var> or <var>Clear</var> option is specified, the behavior of the <var>Modify Buffer</var> statement depends on what other options are used:</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 1,357: Line 1,374:


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


<tr>
<tr>
<td>FILL/CLEAR, SIZE, and PRESERVE are specified </td>
<td><var>Fill</var>/<var>Clear</var>, <var>Size</var>, and <var>Preserve</var> 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>
<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>
</tr>
</table>
</table>
</li>
</li>
Line 1,371: Line 1,387:
====Usage====
====Usage====
<p>
<p>
The MODIFY BUFFER statement requires that you specify at least one option. </p>
The <var>Modify Buffer</var> statement requires that you specify at least one option. </p>
<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>
When you overwrite the contents of the <var>Buffer</var> area, the value of <var>[[$Buffer Used]]</var> is set to zero, and the value of <var>[[$Buffer Position]]</var> is set to one. </p>
<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>
If you exceed the 2-gigabyte limit on the size of <var>Buffer</var>, <var>$Status</var> returns a value of 34. A negative number or a number less than <var>[[UBUFSZ parameter|UBUFSZ]]</var> is changed to <var>UBUFSZ</var>. </p>


==OPEN statement==
<div id="openExt"></div>
==<b id="OPEN statement"></b>Open statement==
<p>
<p>
The OPEN statement opens a sequential file, VSAM file, or terminal for processing.    </p>
The <var>Open</var> statement can be used to open a sequential file, VSAM file, or terminal for processing.    </p>
   
   
====DEFINE DATASET required====
====DEFINE DATASET required====
Line 1,388: Line 1,405:
====Syntax====
====Syntax====
<p>
<p>
The format of the OPEN statement is:</p>
The format of the <var>Open</var> statement for external I/O is:</p>
<p class="syntax">OPEN {[DATASET | EXTERNAL]
{{Template:Open (External I/O) statement syntax}}
{<span class="term">ext-filename</span> | <span class="term">%variable</span>}
| [EXTERNAL] {TERMINAL | <span class="term">%variable</span>}}
FOR {INPUT [OUTPUT] | OUTPUT [INPUT] | INOUT}
[PASSWORD {<span class="term">value</span> | <span class="term">%variable</span>}]
</p>
Where:
Where:
<ul>
<ul>
<li>Either the DATASET or EXTERNAL keyword must be specified to open a sequential (non-<var class="product">Model&nbsp;204</var>) file. DATASET and EXTERNAL should not be specified for opening <var class="product">Model&nbsp;204</var> files.     </li>
<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 DEFINE DATASET command or, for sequential files, the OS DDNAME or CMS FILEDEF. You can provide the external file name can be provided in a %variable.</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>TERMINAL specifies that the entity to be opened is a terminal. The word TERMINAL 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 FOR clause specifies the type of I/O processing that is performed on the opened external file or terminal. An external file or terminal must be at least opened for INPUT to be read into an image and opened for OUTPUT to write data from an image.
<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>
<p>
The INPUT OUTPUT, OUTPUT INPUT, and INOUT combination options are valid only for the TERMINAL keyword.  </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>
 
<li>The PASSWORD clause is required for only password protected VSAM data sets. The clause generates an error when used with an OPEN TERMINAL statement, but is ignored in all other cases.
<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>
<p>
With the PASSWORD clause, the password can be specified directly or can be provided as the value of a %variable. Password validation is performed during evaluation and is not checked during compilation. </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>
</li>
</ul>
</ul>
===Usage notes===
   
   
====Usage notes====
====Open statement in remote context====
====OPEN statement in remote context====
<p>
<p>
This form of the OPEN statement is not supported in remote context. Using the AT keyword with any of the keywords DATASET, EXTERNAL, or TERMINAL generates the following error message, which is not displayed on the terminal, but can be retrieved with the $ERRMSG function:</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 class="code">M204.1497: Remote specification conflicts with open type
</p>
</p>
<p>
If the DATASET or EXTERNAL keyword is not specified and an entity is opened other than a terminal, <var class="product">Model&nbsp;204</var> searches for the name of the file in the following order:  </p>
<ol>
<li><var class="product">Model&nbsp;204</var> temporary groups</li>
<li><var class="product">Model&nbsp;204</var> permanent groups</li>
<li><var class="product">Model&nbsp;204</var> files </li>
</ol>
<p>
This search order is consistent with the search order that <var class="product">Model&nbsp;204</var> uses at command level for the OPEN command. </p>
   
   
====Opening non-Model 204 data sets from within procedures====
====Multiple Opens of external data sets====
<p>
<p>
If a User Language procedure attempts to open an already open non-<var class="product">Model&nbsp;204</var> data set at evaluation time, <var class="product">Model&nbsp;204</var> softly restarts the user with the following counting error message:</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 class="code">M204.2153 Dataset <i>name</i> is already open
</p>
</p>
   
   
====Clearing messages====
====Clearing messages====
<p>
<p>
An OPEN statement automatically clears $FSTERR and $ERRMSG. You can also clear the messages accessed by $FSTERR and $ERRMSG, using the $ERRCLR function; for more details, see [[$ERRCLR#$ERRCLR|$ERRCLR]].</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>
   
   
==POSITION statement==
====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>
<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>
The <var>Position</var> statement specifies the next record to be read sequentially in a VSAM KSDS file. An established position is used by the <var>Read next</var> statement to locate the next record to be returned. A new position can be established at any time by executing another <var>Position</var> statement.  </p>
<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>
This <var>Position</var> statement is not to be confused with the <var>Position</var> statement used to recall a position in a found set or list which has been saved using the <var>Remember</var> option during <var>For</var> loop processing. See [[Global features#Position statement|Position statement]].</p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The format of the POSITION statement is:</p>
The format of the <var>Position</var> statement is:</p>
<p class="syntax">POSITION {<span class="term">ext-filename</span> | <span class="term">%variable</span>}  
<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>}
   At Key <span class="term">operator</span> {<span class="term">value</span> | <span class="term">%variable</span>}
</p>
</p>
Where:
Where:
<ul>
<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.  
<li><var class="term">ext-filename</var> is the name of the VSAM file specified in the <var>Open</var> statement. The name can be provided as the value of a %variable.  
<p>
<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>
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>


<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">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>, <code>EQ</code>, or <code>GE</code>.</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.
<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>
<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>
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 <code>>=</code> or <code>GE</code>. If the operator is <code>=</code> or <code>EQ</code>, a record is found only if it has a key of all binary zeros. </p>
<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>
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>
<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>
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>
</li>
</ul>
</ul>
   
   
==PREPARE statement==
==<b id="PrepareStmtImage"></b>Prepare statement==
<p>
<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>
The <var>Prepare</var> 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. <var>Prepare</var> initializes the block associated with the image with the values specified in the <var>Initial</var> clauses of the item definitions or <var>Default</var> statements. </p>
<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>
Previous identifications of lengths of items defined as length <var>Unknown</var> or number of occurrences of arrays defined with <var>Occurs Unknown</var> are lost. The <var>Identify</var> statement must be executed again to establish length or number of occurrences. </p>
   
   
====Syntax====
====Syntax====
<p>
<p>
The format of the PREPARE statement is:</p>
The format of the <var>Prepare</var> statement is:</p>
<p class="syntax">PREPARE [IMAGE] <span class="term">imagename</span>
<p class="syntax">Prepare [Image] <span class="term">imagename</span>
</p>
</p>
<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>
where <var class="term">imagename</var> refers to an image that was previously described in an image definition. The keyword <var>Image</var> is required if <var class="term">imagename</var> is <code>Image</code>, <code>Menu</code>, or <code>Screen</code>. </p>
   
   
===Use with global images===
===Use with global images===
<p>
<p>
The PREPARE IMAGE statement, when used with global images, can cause request termination due to either: </p>
The <var>Prepare Image</var> statement, when used with global images, can cause request termination due to either: </p>
<ul>
<ul>
<li>Definition mismatches (see [[Global features#Consistency checks performed|Consistency checks performed]] for a description for global images)</li>
<li>Definition mismatches (see [[Global features#Consistency checks performed|Consistency checks performed]] for a description for global images)</li>
   
   
<li>Insufficient space in GTBL (see the
<li>Insufficient space in [[Defining_the_runtime_environment_(CCAIN)#Understanding the global variable table (GTBL)|GTBL]].
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]</var>.
</li>
</li>
</ul>
</ul>
 
==READ IMAGE statement==
==<b id="READ IMAGE statement"></b><b id="Read Image statement"></b><b id="Read Image statement"></b>Read Image statement==
====Purpose====
<p>
<p>
The READ IMAGE statement reads a record from a sequential or VSAM file or terminal into the image and sets the image as the active image. Or, the READ IMAGE statement reads the contents of the Universal Buffer.  </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====
===Syntax===
<p class="syntax">READ [IMAGE] <span class="term">imagename</span> FROM
{{Template:Read Image statement syntax}}
    [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">ext-filename</span> | TERMINAL | <span class="term">%variable</span>}
    [PROMPT {'<span class="term">text</span>' | <span class="term">%variable</span>}]
    [NEXT | KEY <span class="term">operator</span> {<span class="term">value</span> | <span class="term">%variable</span>}]]
</p>
Where:
Where:
<ul>
<ul>
<li><var class="term">imagename</var> is an image that was previously described in an image definition. The keyword IMAGE is required if imagename is IMAGE, MENU, or SCREEN. <var class="term">imagename</var> also specifies a message to read in the Universal Buffer area.</li>
<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 FROM clause determines which use of the READ IMAGE statement to employ:  
<li>The <var>From</var> clause determines which use of the <var>Read</var> <var>Image</var> statement to employ:
<ul>
<ul>
<li>Reading Large Object data from the Universal Buffer</li>
<li>Reading Large Object data from the Universal Buffer</li>
<li>Reading from a sequential file or the terminal</li>
<li>Reading from a sequential file or the terminal</li>
</ul></li>
</ul></li>
<li>BUFFER (formerly, and still accepted as MQ_BUFFER) specifies the Universal Buffer area.</li>
   
   
<li>POSITION must be in the range 1-16,777,216. If not, the operation returns $STATUS=10 and $STATUSD=20 return codes. <var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to begin reading.  
<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>
<p>
If POSITION=<var class="term">%pvariable</var> is specified and <var class="term">%pvariable</var> is greater than $BUFFER_USED, the operation returns $STATUS=10 and $STATUSD=20.</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>
<p>
The starting position in the buffer is determined by POSITION=<var class="term">%pvar</var>, if that was specified; $Buffer_Position, otherwise.</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>
<p>
The ending position in the buffer is determined by the lowest of starting position, plus <var class="term">%lvariable</var>, if MAXLEN=<var class="term">%lvariable</var> was specified as the value of $BUFFER_USED.</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>
 
<li>MAXLEN=%lvariable specifies the maximum number of bytes to copy into the image. The actual number copied might be less than that, either because the number of bytes available in the BUFFER area (from the starting position) is less, or because the size of the image is less.  
<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>
<p>
MAXLEN must be in the range 1-32,767. If not, the operation returns $STATUS=10 and $STATUSD=19.</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>
 
<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 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>TERMINAL specifies that records are read from the terminal. The word TERMINAL 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 PROMPT clause is used with only the TERMINAL option. It specifies to display a prompt sign before the READ is performed. Prompting is especially useful for synchronizing communication between the User Language request and Host Language program.  
<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>
<p>
The PROMPT string can be as many as 255 characters. The string can be provided as a string type %variable.</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>
<li>The NEXT option reads the next record in the file. NEXT is the default, if the KEY clause is omitted. A READ IMAGE statement with the NEXT option can be executed only following an OPEN, POSITION, or READ NEXT statement.    </li>
   
   
<li>The KEY clause identifies the record to read. The KEY clause is valid only for VSAM files and the value is converted to a string. A READ IMAGE statement with the KEY clause automatically performs a RELEASE POSITION.
<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>
<p>
Key clause options are <var class="term">operator</var> and <var class="term">value</var>:</p>
<var>Key</var> clause options are <var class="term">operator</var> and <var class="term">value</var>:</p>
<ul>
<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: =, >=, EQ, or GE.</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: <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.
<li><var class="term">value</var> is the key that locates the record. It can be supplied in a %variable.
<p>
<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 >= or GE. If the operator is = or EQ, a record is found only if it has a key of all binary zeros. If the length of 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>
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>
</li>
</ul>
</ul>
Line 1,563: Line 1,566:
</li>
</li>
</ul>
</ul>
 
====Usage====
===Usage===
<p>
<p>
This statement is valid only if the file or terminal from which the record is read is currently open for INPUT, INPUT OUTPUT, or INOUT. READ IMAGE processing reads data until the Universal Buffer is exhausted, or the image is filled. </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>
<p>
The part of the message selected is copied from BUFFER area to the image:</p>
The part of the message selected is copied from the Universal Buffer to the image:</p>
<ul>
<ul>
<li>Contents of the BUFFER area are unchanged.</li>
<li>Contents of the Universal Buffer are unchanged.</li>
   
   
<li>$BUFFER_USED is unchanged.</li>
<li><var>$Buffer_Used</var> is unchanged.</li>
   
   
<li>$Buffer_Position is set to the byte after the last byte copied.</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>No error indication is given, if the image is not big enough to hold the data.
</li>
</li>
</ul>
</ul>
 
===BUFFER area positioning===
===Buffer area positioning===
<p>
<p>
If POSITION is specified:</p>
If <var>Position</var> is specified:</p>
<ul>
<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>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; READLEN is set to 0. </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 $STATUS value.  
<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>
</li>
</ul>
</ul>
<p>
<p>
If the POSITION option is not specified:</p>
If the <var>Position</var> option is not specified:</p>
<ul>
<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>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 READ statements that do not specify POSITION set READLEN to 0, and leave the target image unchanged.
<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>
</li>
</ul>
</ul>
<p>
<p>
After a READ IMAGE statement is issued, use the value of READLEN to determine how many bytes were actually copied. If no bytes were copied, READLEN=0.</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>
<p>
The bytes in the image at offsets higher than the READLEN value are unchanged.</p>
The bytes in the image at offsets higher than the <var>ReadLen</var> value are unchanged.</p>
<p>
<p>
To determine the number of bytes remaining, use the following formula: </p>
To determine the number of bytes remaining, use the following formula: </p>
<p class="code">bytes remaining = ($BUFFER_USED - $buffer_position + 1)
<p class="code">bytes remaining = ($Buffer_Used - $Buffer_Position + 1)
</p>
</p>
 
===Record positioning===
===Record positioning===
<p>
<p>
If no position has been set prior to a READ NEXT, the position is assumed to be at the beginning of the file.</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>
<p>
The record is positioned in the image according to the following rules:</p>
The record is positioned in the image according to the following rules:</p>
Line 1,616: Line 1,620:
<li>If the record is longer than the image, the record is truncated.</li>
<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 INITIAL value. An item that is partially filled by the input data is filled with the pad character for STRING and EFORMAT items and with binary zeros for BINARY, PACKED, ZONED, and FLOAT items.</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 INITIAL clauses. The remaining data is move to the image following the array.</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 UNKNOWN, the block is filled with as much of the external record as fits in the remaining physical buffer space.
<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>
</li>
</ul>
</ul>
Line 1,626: Line 1,630:
===Length of the external record===
===Length of the external record===
<p>
<p>
The length of the external record is stored in the variable <var class="term">%imagename</var>:READLEN.  </p>
The length of the external record is stored in the variable <code><i>%imagename</i>:ReadLen</code>.  </p>
<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>
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>
   
 
==RELEASE POSITION statement==
===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 pwd ends, say, in a hyphen
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>
<p>
The RELEASE POSITION statement terminates a browse operation established by a POSITION statement. </p>
The <var>Release Position</var> statement terminates a browse operation established by a <var>Position</var> statement. </p>
<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>
Execution of a <var>Release Position</var> 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 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>
</p>
<p class="note"><b>Note:</b> A <var>Position</var> statement automatically is released by another <var>Position</var> statement, a <var>Read Image</var> statement with a <var>Key</var> clause, a <var>Close</var> statement, or the end of the request. </p>
   
   
====Syntax====
===Syntax===
<p>
<p>
The format of the RELEASE POSITION statement is:</p>
The format of the <var>Release Position</var> statement is:
<p class="syntax">RELEASE POSITION {<span class="term">ext-filename</span> | <span class="term">%variable</span>}
</p>
</p>
{{Template:Release Position statement syntax}}
Where:
Where:
<p>
<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>
<var class="term">ext-filename</var> is the name of the external file used in the <var>Position</var> statement. A %variable also can be used to supply the external file name. </p>
   
   
==WRITE IMAGE statement==
==Write Image statement==
====Purpose====
<p>
<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>
The <var>Write Image</var> statement loads data into the Universal Buffer, or it writes an active image to a sequential file or to the terminal.</p>
   
   
====Syntax====
===Syntax===
<p>
<p>
The format of the WRITE IMAGE statement is:</p>
The format of the <var>Write Image</var> statement is: </p>
<p class="syntax">WRITE [IMAGE] <span class="term">imagename</span> ON
{{Template:Write Image statement syntax}}
      [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:
Where:
<ul>
<ul>
<li><var class="term">imagename</var> specifies a message to place in the message buffer.</li>
<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>The <var>On</var> clause determines which use of the <var>Write Image</var> 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>Buffer</var> (formerly, and still accepted as <code>Mq_Buffer</code>) 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><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.  
<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>.  
<p>
<p>
The starting position in the buffer is determined by:</p>
The starting position in the buffer is determined by: </p>
<ul>
<ul>
<li>POSITION=<var class="term">%pvariable</var>, if that was specified.</li>
<li><var>Position=<i>%pvariable</i></var>, if that was specified. </li>
<li>$Buffer_Position, otherwise.</li>
<li><var>$Buffer_Position</var>, otherwise. </li>
</ul></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.  
<li><var>Maxlen=<i>%lvariable</i></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>
<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>
<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>. The amount of data to copy is determined by:</p>
<table>
<table>
<tr class="head">
<tr class="head">
<th>If MAXLEN=<i>%lvar</i> is </th>
<th>If Maxlen=<i>%lvar</i> is </th>
<th>Then copy...</th>
<th>Then copy...</th>
</tr>
</tr>
Line 1,701: Line 1,735:
<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><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.   
<li><var>Terminal</var> specifies that the image should be written to the terminal. A %variable also can be used to supply the word <code>Terminal</code>.   
<p>
<p>
If you specify the TERMINAL option on the WRITE IMAGE statement, data type translation is not performed for the terminal output.  </p>
If you specify the <var>Position</var> option on the <var>Write Image</var> statement, data type translation is not performed for the terminal output.  </p></li>
</li>
</ul>
</ul>


====Usage====
===Usage===
<p>
<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>
The <var>Write Image</var> 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 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>
<p class="note"><b>Note:</b> When the <var>Write Image</var> statement is used for a depending array, unused occurrences of the array are eliminated from the output.</p>
<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>
If an <var>MqPut</var> or <var>MqPut1</var> statement is issued with the <var>Buffer</var> option, the buffer must contain a message, otherwise the operation fails with a nonzero <var>$Status</var> value.</p>
<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>
If the last WebSphere MQ operation was a successful put or get, then an <var>MqPut</var> or <var>MqPut1</var> statement with the BUFFER options puts the message most recently processed. In all other cases, at least one <var>Write Image <i>imagename</i> On Buffer</var> statement must have been issued.
<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>
</p>
<p class="note"><b>Note:</b> Issue an <var>MqPut</var> statement with the <var>Buffer</var> option after a <var>Write Image <i>imagename</i> On Buffer</var> statement, otherwise <var>$Status</var> indicates there is no data in the buffer.</p>
   
   
====Image positioning====
===Image positioning===
<p>
<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>
The data in the image is loaded into the buffer. Where the data is placed in the buffer depends on whether the <var>Position</var> option was specified. </p>
<p>
<p>
If POSITION was not specified:</p>
If <var>Position</var> was not specified:</p>
<ul>
<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 the first such <var>Write Image</var> after any other SOUL 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>On subsequent <var>Write Image</var> statements, data is loaded immediately following the data from the most recent WRITE. </li>
</li>
</ul>
</ul>
<p>
<p>
If POSITION is specified as:</p>
If <var>Position</var> is specified as:</p>
<ul>
<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>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>Nonnumeric, less than one, or larger than the current size of the buffer, then the statement fails with a nonzero <var>$Status</var> value.  
</li>
</li>
</ul>
</ul>
Line 1,743: Line 1,777:
The data is copied from the image to the BUFFER area:</p>
The data is copied from the image to the BUFFER area:</p>
<ul>
<ul>
<li>$BUFFER_POSITION is set to the byte after the last byte copied.</li>
<li><var>$Buffer_Position</var> 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><var>$Buffer_Used</var> is set according to the following rule: if data was written past the previous <var>$Buffer_Used</var> point, then <var>$Buffer_Used</var> is the point written to by the <var>Write Image</var>; otherwise, it is unchanged. </li>
</li>
</ul>
</ul>
 
==Error handling==
==Error handling==
<p>
<p>
Error conditions encountered during the processing of image I/O statements &mdash; CLOSE, OPEN, POSITION, READ IMAGE, RELEASE POSITION, and WRITE IMAGE &mdash; generate <var class="product">Model&nbsp;204</var> error messages that are not displayed on the terminal. </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>
<p>
The request should check for errors after the execution of each I/O statement by using the $STATUS function. The text of the most recently issued error message then can be retrieved by using the $ERRMSG function. Refer to [[$ERRCLR#$ERRCLR|$ERRCLR]] and [[$STATUS#$STATUS|$STATUS]] for more information.  </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===
===$Status return codes===
<p>
<p>
The values that can be returned by $STATUS are listed below:</p>
The values that can be returned by <var>$Status</var> are listed below:</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 1,765: Line 1,798:


<tr>
<tr>
<td align="right">0</td>
<td>0</td>
<td>The operation was successful. A return code of 0 also clears the message buffer. Therefore, the $ERRMSG function, if called, returns a null string.</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>


<tr>
<tr>
<td align="right">1</td>
<td>1</td>
<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>
Either an end of file was detected by a READ NEXT statement or a matching key was not found for the criteria specified in a READ KEY or POSITION statement. </p>
<p>
<p>
This code is only a warning; the request continues but cannot refer to the image before the next READ KEY or POSITION 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>
</td></tr>
</tr>


<tr>
<tr>
<td align="right">2</td>
<td>2</td>
<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>
A serious error has occurred such as an OPEN statement failure or an attempt to access an unopened file. The request continues, but the statement that generated the status code has not completed successfully. </p>
<p>
<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>
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>
<p>
The error that occurred can be retrieved by using the $ERRMSG function to obtain the last counting or cancellation error message produced by <var class="product">Model&nbsp;204</var>.  </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>
</td></tr>
</tr>
</table>
</table>
   
   
===Detecting ABEND codes in User Language===
===Detecting ABEND codes in SOUL===
<p>
<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 $STATUS and $STATUSD are set as follows:</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>
<table>
<tr class="head">
<tr class="head">
Line 1,803: Line 1,830:


<tr>
<tr>
<td>$STATUS</td>
<td>$Status</td>
<td>System ABEND code</td>
<td>System ABEND code</td>
<td>System code is not zero</td>
<td>System code is not zero</td>
Line 1,809: Line 1,836:


<tr>
<tr>
<td>$STATUS</td>
<td>$Status</td>
<td>User ABEND code</td>
<td>User ABEND code</td>
<td>User code is not zero</td>
<td>User code is not zero</td>
Line 1,815: Line 1,842:


<tr>
<tr>
<td>$STATUS</td>
<td>$Status</td>
<td>255 (X'FF')</td>
<td>255 (X'FF')</td>
<td>ABEND code => X'F00'</td>
<td>ABEND code => X'F00'</td>
Line 1,821: Line 1,848:


<tr>
<tr>
<td>$STATUSD</td>
<td>$StatusD</td>
<td>Concatenated values of the $STATUS values:</td>
<td>Concatenated values of the $Status values:</td>
<td>
<td><var class="term">sss</var> is the system ABEND code
<p>
<var class="term">sss</var> is the system ABEND code</p>
<p>
<p>
<var class="term">uuu</var> is the user ABEND code</p>
<var class="term">uuu</var> is the user ABEND code</p>
<p>
<p>
<var class="term">rr</var> is the ABEND reason code</p>
<var class="term">rr</var> is the ABEND reason code</p>
</td>
</td></tr>
</tr>
</table>
</table>
<p>
<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 $STATUS and $STATUSD with the result of the Terminal I/O and so override the ABEND code information.</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 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>
<p>
The ABEND code is not available in the z/VSE environment.</p>
The ABEND code is not available in the z/VSE environment.</p>
 
==Sample requests==
==Sample requests==
<p>
<p>
Line 1,854: Line 1,878:
         OPEN DATASET VSAMDS1 FOR INPUT
         OPEN DATASET VSAMDS1 FOR INPUT
         IF $STATUS NE 0 THEN
         IF $STATUS NE 0 THEN
             PRINT $ERRMSG
             PRINT $Errmsg
             STOP
             STOP
         END IF
         END IF
Line 1,865: Line 1,889:
             PRINT 'RECORD NOT FOUND'
             PRINT 'RECORD NOT FOUND'
         ELSEIF $STATUS EQ 2 THEN
         ELSEIF $STATUS EQ 2 THEN
             PRINT $ERRMSG
             PRINT $Errmsg
             JUMP TO EXIT
             JUMP TO EXIT
         ELSE
         ELSE
             PRINT 'CODE = ' WITH %EMP.REC:CODE
             PRINT 'CODE = ' WITH %EMP.REC:CODE
             PRINT 'JOB DESCRIPTION = ' WITH -
             PRINT 'JOB DESCRIPTION = ' WITH %EMP.REC:JOB.DESC
                %EMP.REC:JOB.DESC
             PRINT 'NUMBER = ' WITH %EMP.REC:NUM
             PRINT 'NUMBER = ' WITH %EMP.REC:NUM
         END IF
         END IF
Line 1,878: Line 1,901:
</p>
</p>
<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>
The preceding request could be rewritten in the manner shown in the next example to print information from ten successive records of the VSAM file. </p>
   
   
===Using a POSITION statement===
===Using a Position statement===
<p>
<p>
The starting position in this example is established in the file through the use of the POSITION statement and a user-specified key.</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
<p class="code">BEGIN
         IMAGE EMP.REC
         IMAGE EMP.REC
Line 1,889: Line 1,912:
             NUM IS STRING LEN 7 DP *
             NUM IS STRING LEN 7 DP *
         END IMAGE
         END IMAGE
         OPEN DATASET VSAMDS1 FOR INPUT                                             IF $STATUS NE 0 THEN
         OPEN DATASET VSAMDS1 FOR INPUT  
                 PRINT $ERRMSG
            IF $STATUS NE 0 THEN
                 PRINT $Errmsg
                 STOP
                 STOP
             END IF
             END IF
Line 1,904: Line 1,928:
                     JUMP TO PROMPT
                     JUMP TO PROMPT
                 ELSEIF $STATUS EQ 2 THEN
                 ELSEIF $STATUS EQ 2 THEN
                     PRINT $ERRMSG
                     PRINT $Errmsg
                     JUMP TO EXIT
                     JUMP TO EXIT
                 ELSE
                 ELSE
                     PRINT 'CODE = ' WITH %EMP.REC:CODE
                     PRINT 'CODE = ' WITH %EMP.REC:CODE
                     PRINT 'JOB DESCRIPTION = ' WITH -
                     PRINT 'JOB DESCRIPTION = ' WITH %EMP.REC:JOB.DESC
                        %EMP.REC:JOB.DESC
                     PRINT 'NUMBER = ' WITH %EMP.REC:NUM
                     PRINT 'NUMBER = ' WITH %EMP.REC:NUM
                 END IF
                 END IF
Line 1,920: Line 1,943:
===Example===
===Example===
<p>
<p>
The following request reads a sequential file that contains output from a previously issued PRINT ALL INFORMATION (PAI) statement. The foundset data is now in a data set. The request also handles non-PAI lines that might be found in the sequential file as separators; see the sample output that follows. The file being processed in this request contains PAI data for a CENSUS file.</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
<p class="code">BEGIN
IMAGE PAI
IMAGE PAI
Line 1,933: Line 1,956:
           JUMP TO DONE
           JUMP TO DONE
       ELSEIF $STATUS EQ 2 THEN
       ELSEIF $STATUS EQ 2 THEN
           PRINT 'OPEN ERROR: ' WITH $ERRMSG
           PRINT 'OPEN ERROR: ' WITH $Errmsg
           STOP
           STOP
       END IF
       END IF
Line 1,940: Line 1,963:
           JUMP TO DONE
           JUMP TO DONE
       ELSEIF $STATUS EQ 2 THEN
       ELSEIF $STATUS EQ 2 THEN
           PRINT 'READ ERROR: ' WITH $ERRMSG
           PRINT 'READ ERROR: ' WITH $Errmsg
           STOP
           STOP
       END IF
       END IF
Line 1,959: Line 1,982:
<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>
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>*
<p class="output"><b></b>*
FIELD='HOUSEHOLD ID'        VALUE='53690'
FIELD='HOUSEHOLD ID'        VALUE='53690'
FIELD='AGE'                VALUE='21'
FIELD='AGE'                VALUE='21'

Latest revision as of 07:45, 9 July 2018

Overview

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

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

Terminology

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

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

Global images

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

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

Using images

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

Reading external files or terminal input

Input sources

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

Input sources Description
Sequential or VSAM files Any number of sequential or VSAM files can be read and processed. If VSAM files are used, the files must be keyed sequential (KSDS). KSDS files can be accessed using an alternate index path.

For more information on the types of files and keys that can be used, see the DEFINE DATASET command.

Terminal Terminal input can be read and processed. A terminal can consist of the physical device on which the request is run, or a User Language connection that has been made from a Host Language application program by using the IFDIAL function.

External records

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

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

Reading records into an image

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

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

Writing to sequential files or a terminal

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

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

Defining storage blocks

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

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

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

Possible uses

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

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

Defining an image

Managing blocks

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

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

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

Define an image before referring to it

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

Understanding how data is described by images

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

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

Image components

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

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

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

Concurrent access to multiple records of the same format

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

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

Image naming and reference conventions

Rules for image names

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

Rules for item names and array names

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

Rule for reserved item names

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

Do not duplicate names in the same block

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

References

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

%imagename:itemname

For example:

%INVENTORY:PART.NO

identifies the item PART.NO in the image INVENTORY.

Image and End Image statements

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

Syntax

The format of the Image block is:

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

where global is:

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

Where:

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

    Note:

    • You must not specify the Global attribute for an image that has an image item defined with either of the following attributes:
      • Occurs Unknown
      • Len Unknown
    • Images that share a block must have the same scope. For multi-image blocks, you can specify only the first image as Global; you must not specify subsequent images in a multi-image block as Global. Specifying the first image as Global, declares the entire block of images as Global. The same behavior and restrictions apply to Common images in a block.
  • Permanent can be used only with global images. Permanent global images persist across request boundaries; that is, they are maintained in GTBL even after a request has been terminated.
  • Temporary can be used with only global images. Temporary global images are allocated in GTBL, but are deleted at request termination. For example, use a Temporary global image when you do not need to pass the image to another request; using Temporary global images eliminates the need to explicitly delete globals that do not need to persist.
  • Common images, or images that are neither Common nor Global, are stored in FSCB.

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

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

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

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

End Image statement

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

The format of this statement is:

End Image

Examples of image definitions

Single image definition

An example of the definition of a single image follows:

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

Multiple image definition for the same block

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

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

Multiple image definition with shared items

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

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

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

Special considerations for multiple-image blocks

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

Using uninitialized disk space

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

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

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

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

Using initialized disk space

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

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

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

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

Defining image items

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

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

Syntax

The general format of an item definition is:

itemname [Is [Type] type description]

Where:

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

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

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

Defining a string item

Syntax

Define string items with this syntax:

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

Where:

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

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

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

After and At clauses

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

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

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

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

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

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

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

Occurs clause

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

Defining a binary item

Syntax

Define binary items with this syntax:

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

Where:

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

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

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

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

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

    The Alignoption cannot be specified for an item:

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

Defining a packed decimal item

Syntax

Define packed decimal items with this syntax:

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

Where:

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

Defining a zoned decimal item

Syntax

Define zoned decimal items with this syntax:

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

Where:

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

Defining a floating point item

Syntax

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

Where:

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

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

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

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

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

    The Align option cannot be specified for an item:

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

Defining an exponential notation item

Syntax

Define exponential notation items with this syntax:

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

Where:

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

Item definition examples

An image containing various item types

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

Using the At and After clauses

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

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

Defining arrays

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

Array definition statements

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

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

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

Types of arrays

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

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

Array and End Array statements

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

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

Defining a fixed occurrence array

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

Syntax

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

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

Where:

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

Example

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

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

The same image could be written as:

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

Defining a depending array

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

Depending variable

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

The depending variable is used in this manner:

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

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

Restrictions

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

Syntax

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

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

Where:

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

Example

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

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

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

Defining an unknown array

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

Syntax

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

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

Where:

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

Example

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

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

Referring to array elements

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

Nested arrays

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

Example

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

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

Initialization of array values

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

Example 1

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

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

Example 2

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

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

Example 3

The following example prints AAA and 100:

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

Example 4

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

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

Using Large Object fields with a very large array

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

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

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

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

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

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

Defining reserved space

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

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

Skip statement

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

Syntax

The format of the Skip statement for reserving space is:

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

Where:

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

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

Example

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

SKIP 2 POSITIONS

Default Type and Default Skip statements

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

  • Default Type
  • Default Skip

Default Type statement

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

Syntax

The format of the Default Type statement is:

Default [Type] type options

Where:

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

Default Skip statement

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

Syntax

The format of the Default Skip statement is:

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

Where:

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

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

Example of Default statements

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

Without Default statements

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

With Default statements

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

Processing images

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

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

Key field for VSAM files

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

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

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

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

Close statement

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

Syntax

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

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

Where:

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

Closing a Model 204 file

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

Identify statement

The Identify statement establishes:

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

Syntax

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

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

Where:

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

Establishing an active image

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

Identify [Image] imagename

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

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

Use with global images

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

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

Establishing lengths for Unknown items

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

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

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

Establishing occurrences for Unknown arrays

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

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

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

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

Modify Buffer statement

Function

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

Syntax

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

Where:

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

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

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

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

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

Usage

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

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

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

Open statement

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

DEFINE DATASET required

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

Syntax

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

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

Where:

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

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

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

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

Usage notes

Open statement in remote context

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

M204.1497: Remote specification conflicts with open type

Multiple Opens of external data sets

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

M204.2153 Dataset name is already open

Clearing messages

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

See also

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

Position statement

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

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

Syntax

The format of the Position statement is:

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

Where:

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

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

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

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

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

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

Prepare statement

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

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

Syntax

The format of the Prepare statement is:

Prepare [Image] imagename

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

Use with global images

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

Read Image statement

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

Syntax

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

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

Where:

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

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

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

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

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

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

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

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

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

    Key clause options are operator and value:

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

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

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

Usage

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

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

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

Buffer area positioning

If Position is specified:

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

If the Position option is not specified:

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

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

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

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

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

Record positioning

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

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

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

Length of the external record

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

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

Usage notes

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

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

If the above procedure is invoked as:

INCLUDE FOO MYFILE

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

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

Release Position statement

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

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

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

Syntax

The format of the Release Position statement is:

Release Position {ext-filename | %variable}

Where:

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

Write Image statement

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

Syntax

The format of the Write Image statement is:

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

Where:

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

    The starting position in the buffer is determined by:

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

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

    If Maxlen=%lvar is Then copy...
    Not specified Current length of the image.
    Specified Lesser of %lvariable and the current length of the image.
  • seq-filename specifies the name of the sequential file to which the image should be written. A %variable also can be used to supply the name of the sequential file.
  • Terminal specifies that the image should be written to the terminal. A %variable also can be used to supply the word Terminal.

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

Usage

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

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

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

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

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

Image positioning

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

If Position was not specified:

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

If Position is specified as:

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

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

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

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

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

Error handling

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

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

$Status return codes

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

Code Description
0 The operation was successful. A return code of 0 also clears the message buffer. Therefore, the $Errmsg function, if called, returns a null string.
1 Either an end of file was detected by a Read Next statement or a matching key was not found for the criteria specified in a Read Key or Position statement.

This code is only a warning; the request continues but cannot refer to the image before the next Read Key or Position statement.

2 A serious error has occurred such as an Open statement failure or an attempt to access an unopened file. The request continues, but the statement that generated the status code has not completed successfully.

The failed statement cannot set an image active, resulting in the cancellation of the request if the image is referred to before being set active.

The error that occurred can be retrieved by using $Errmsg to obtain the last counting or cancellation error message produced by Model 204.

Detecting ABEND codes in SOUL

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

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

uuu is the user ABEND code

rr is the ABEND reason code

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

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

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

Sample requests

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

Using the READ KEY facility

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

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

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

Using a Position statement

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

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

Example

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

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

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

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