m204wiki - User contributions [en]

DEFINE PROCESSGROUP command: Horizon for TCP/IP

2016-02-23T23:03:04Z

Tbullock: OUTLIMIT is in the examples and M204 will take it, don't know what it does though.

==Summary==
<dl>
<dt>Privileges
<dd>User 0 or system manager
<dt>Function
<dd>Sets up a TCP/IP connection via Horizon for processgroup. Supported in all operating systems.
</dl>
==Syntax==
DEFINE PROCESSGROUP name [LIKE previousname] WITH
SCOPE=SYSTEM
LINK=linkname
REMOTEID={address | symbolicaddress} LOOKUP=IPV6ONLY|IPV4ONLY|ANY
INLIMIT={nnnn | 0}
OUTLIMIT={nnnn | 0}
[PORT=nnnnn]
[GUESTUSER={ACCEPT | REJECT}]
[LOGIN=TRUST | NOTRUST}]
[MASK={dotted-decimal | 255.255.255.255}]


Where:
<ul>
<li>
name is used on DEFINE PROCESS commands to refer to this processgroup. The length of the name must be eight characters or less. ALL is a reserved word and cannot be used. 
</li>

<li>
<var>LINK</var> is required and associates the group with a locally defined link that implies the transport type and conversation protocol. A linkname must match the name used in a local DEFINE LINK command. 
</li>

<li>
REMOTEID=address specifies the network address of one or, if a mask is specified, many partner remote nodes in the network. 
address can be: 
<ul>
<li>
a 32-bit number written in dotted-decimal notation, such as 182.148.55.206
</li>

<li>
(z/OS only) an IPv6 address, with up to 8 halfwords separated by colons, such as 
C0:12:46:F0:00:00:00:01
, which can also be written as 
C0:12:46:F0::01
. In other words, the double colon shows that there are missing halfwords of binary zeros.
</li>
</ul>
REMOTEID=symbolicaddress specifies the symbolic address of one partner remote node in the network, such as MYMVS1, or SMTP.MYDOMAIN.COM. 
The MASK parameter cannot be used with REMOTEID=symbolicaddress. 
</li>
</ul>

==Example==
To set up a Horizon for TCP/IP connection, take the following steps. You define a link, processgroup, and a process for a client and open the link. Then you define the same items on the server side and open the link, as shown in the following steps.
For the client
<ol>
<li>
Define a link for a client named TCPC. 
DEFINE LINK TCPC WITH SCOPE=SYSTEM PROTOCOL=IP -
LOCALID=192.207.28.129 INBUFSIZE=4096 -
TRANSPORT=TCPSE -
CONNECTIONS=60 SERVPORT=65535

</li>

<li>
Define a processgroup named TCPG
DEFINE PROCESSGROUP TCPG WITH SCOPE=SYSTEM LINK=TCPC -
INLIMIT=30 OUTLIMIT=30 REMOTEID=192.207.28.129 -
MASK=255.255.255.255 PORT=65534

The value of PORT, 65534, is used as the SERVPORT value in the DEFINE LINK command for the server.
</li>

<li>
Define a process named CPR
DEFINE PROCESS CPR WITH SCOPE=SYSTEM -
DATALEN=9999 PARTNER=SPR -
DESTINATION=TCPG UIDSOURCE=OPEN

The value of PARTNER, SPR, is the process name in the DEFINE PROCESS command for the server.
</li>

<li>
Open the client link named TCPC
OPEN LINK TCPC

</li>
</ol>
For the server
<ol>
<li>
Define a link for the server named TCPS that corresponds to the link for the client. In this example, the SERVPORT value 65534 matches the PORT value defined in the client DEFINE PROCESSGROUP command.
DEFINE LINK TCPS WITH SCOPE=SYSTEM PROTOCOL=IP -
LOCALID=192.207.28.129 INBUFSIZE=4096 -
TRANSPORT=TCPSE -
CONNECTIONS=60 SERVPORT=65534

</li>

<li>
Define a processgroup TSPG for the server
DEFINE PROCESSGROUP TSPG WITH SCOPE=SYSTEM - LINK=TCPS -
INLIMIT=30 OUTLIMIT=30 REMOTEID=192.207.28.129 -
MASK=255.255.255.255

</li>

<li>
Define a process named SPR for the server
DEFINE PROCESS SPR WITH SCOPE=SYSTEM FROM TSPG -
DATALEN=9999 TIMEOUT=0 -
SUBSYSTEM=CONS SUBSYSPARM='CONSPROC RE-TPROC - NOPEN'

The process name defined for the server must match the value of the PARTNER parameter in the client DEFINE PROCESS command.
</li>

<li>
Open the server link named TCPS
OPEN LINK TCPS

</li>
</ol>
==Usage notes==
IPv6 addressing
IPv6 addressing is supported on IBM z/OS systems only.
Take care using symbolic addresses when your Online is running on a host that is enabled for IPv6 addressing. If your Online needs to communicate with IPv4 partner nodes, you must specify LOOKUP=IPV4ONLY on the LINK or PROCESSGROUP definition. For details, see "Usage Notes" in [[DEFINE LINK command: Horizon for TCP/IP|DEFINE LINK: Horizon for TCP/IP]].
[[Category: System manager commands]]
[[Category:Commands]]

DaysToString (Float function)

2015-12-28T21:11:49Z

Tbullock: This one takes positive number only for some reason.

{{Template:Float:DaysToString subtitle}}

The <var>DaysToString</var> [[Intrinsic classes|intrinsic]] function operates on a <var>Float</var> value representing days since 1900 and returns a formatted string representing that date/time.

==Syntax==
{{Template:Float:DaysToString syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>A variable to receive the formatted [[Datetime_string_formats|date/time string]] result of the <var>DaysToString</var> method.</td></tr>
<tr><th>float</th><td>A <var>Float</var> value representing days since 1900. Range 0 - 2958463.</td></tr>
<tr><th>format</th><td>A valid [[Datetime_string_formats|date/time string format]].</td></tr>
</table>

==Usage notes==
<ul>
<li>The <var>DaysToString</var> function is available as of <var class="product">Sirius Mods</var> Version 7.8.
</ul>

==Examples==
<ol>
<li>These statements use <var>DaysToString</var> and <var>[[StringToDays (String_function)|StringToDays]]</var> to convert a value in <code>MM/DD/YY</code> format to the <code>Month DAY, YYYY</code> format. They also show the effect of the <var>CentSpan</var> parameter:
printText {~='12/22/11':stringToDays('MM/DD/YY', centspan=2000):daysToString('Month DAY, YYYY')}

printText {~='12/22/11':stringToDays('MM/DD/YY', centspan=1910):daysToString('Month DAY, YYYY')} 

The results are:
'12/22/11':stringToDays('MM/DD/YY', centspan=2000):daysToString('Month DAY, YYYY')=December 22, 2011

'12/22/11':stringToDays('MM/DD/YY', centspan=1910):daysToString('Month DAY, YYYY')=December 22, 1911 

<li>See also the <var>StringToDays</var> [[StringToDays (String function)#Examples|examples]].
</ol>

==See also==
<ul>
<li>Related intrinsic methods (provide conversion from one form of date representation to another):
<ul>
<li><var>[[MillisecondsToString (Float_function)|MillisecondsToString ]]</var>
<li><var>[[SecondsToString (Float_function)|SecondsToString]]</var>
<li><var>[[StringToDays (String_function)|StringToDays]]</var>
<li><var>[[StringToMilliseconds (String_function)|StringToMilliseconds]]</var>
<li><var>[[StringToSeconds (String_function)|StringToSeconds]]</var>
<li><var>[[TimeStringConvert (String_function)|TimeStringConvert]]</var>
</ul>
<li>Related <var>System</var> methods:
<ul>
<li><var>[[CurrentTimeMilliseconds (System function)|CurrentTimeMilliseconds]]</var>
<li><var>[[CurrentTimeSeconds (System function)|CurrentTimeSeconds]]</var>
<li><var>[[CurrentTimeDays (System function)|CurrentTimeDays ]]</var>
<li><var>[[CurrentTimeString (System function)|CurrentTimeString ]]</var>
</ul>
</ul>
{{Template:Float:DaysToString footer}}

MillisecondsToString (Float function)

2015-12-28T20:51:44Z

Tbullock: Oops never mind

{{Template:Float:MillisecondsToString subtitle}}

The <var>MillisecondsToString</var> [[Intrinsic classes|intrinsic]] function operates on a <var>Float</var> value representing milliseconds since 1900 and returns a formatted string representing that date/time.

==Syntax==
{{Template:Float:MillisecondsToString syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>A variable to receive the formatted [[Datetime_string_formats|date/time string]] result of the <var>MillisecondsToString</var> method.</td></tr>
<tr><th>float</th><td>A <var>Float</var> value representing milliseconds since 1900. Range -4638816000000 - 255611289599999.</td></tr>
<tr><th>format</th><td>A valid [[Datetime_string_formats|date/time string format]].</td></tr>
</table>

==Examples==
See the <var>StringToMilliseconds</var> [[StringToMilliseconds (String function)#Examples|example]].

==See also==
<ul>
<li>Related intrinsic methods (provide conversion from one form of date representation to another):
<ul>
<li><var>[[DaysToString (Float_function)|DaysToString]]</var>
<li><var>[[SecondsToString (Float_function)|SecondsToString]]</var>
<li><var>[[StringToDays (String_function)|StringToDays]]</var>
<li><var>[[StringToMilliseconds (String_function)|StringToMilliseconds]]</var>
<li><var>[[StringToSeconds (String_function)|StringToSeconds]]</var>
<li><var>[[TimeStringConvert (String_function)|TimeStringConvert]]</var>
</ul>
<li>Related <var>System</var> methods:
<ul>
<li><var>[[CurrentTimeMilliseconds (System function)|CurrentTimeMilliseconds]]</var>
<li><var>[[CurrentTimeSeconds (System function)|CurrentTimeSeconds]]</var>
<li><var>[[CurrentTimeDays (System function)|CurrentTimeDays ]]</var>
<li><var>[[CurrentTimeString (System function)|CurrentTimeString ]]</var>
</ul>
</ul>
{{Template:Float:MillisecondsToString footer}}

MillisecondsToString (Float function)

2015-12-28T20:48:02Z

Tbullock: Same thing x 1000

{{Template:Float:MillisecondsToString subtitle}}

The <var>MillisecondsToString</var> [[Intrinsic classes|intrinsic]] function operates on a <var>Float</var> value representing milliseconds since 1900 and returns a formatted string representing that date/time.

==Syntax==
{{Template:Float:MillisecondsToString syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>A variable to receive the formatted [[Datetime_string_formats|date/time string]] result of the <var>MillisecondsToString</var> method.</td></tr>
<tr><th>float</th><td>A <var>Float</var> value representing milliseconds since 1900. Range -4638816000000 - 255611289599999.</td></tr>
<tr><th>format</th><td>A valid [[Datetime_string_formats|date/time string format]].</td></tr>
</table>

==Examples==
See the <var>StringToMilliseconds</var> [[StringToMilliseconds (String function)#Examples|example]].

==See also==
<ul>
<li>Related intrinsic methods (provide conversion from one form of date representation to another):
<ul>
<li><var>[[DaysToString (Float_function)|DaysToString]]</var>
<li><var>[[SecondsToString (Float_function)|SecondsToString]]</var>
<li><var>[[MillisecondsToString (Float_function)|MillisecondsToString]]</var>
<li><var>[[StringToDays (String_function)|StringToDays]]</var>
<li><var>[[StringToMilliseconds (String_function)|StringToMilliseconds]]</var>
<li><var>[[StringToSeconds (String_function)|StringToSeconds]]</var>
<li><var>[[TimeStringConvert (String_function)|TimeStringConvert]]</var>
</ul>
<li>Related <var>System</var> methods:
<ul>
<li><var>[[CurrentTimeMilliseconds (System function)|CurrentTimeMilliseconds]]</var>
<li><var>[[CurrentTimeSeconds (System function)|CurrentTimeSeconds]]</var>
<li><var>[[CurrentTimeDays (System function)|CurrentTimeDays ]]</var>
<li><var>[[CurrentTimeString (System function)|CurrentTimeString ]]</var>
</ul>
</ul>
{{Template:Float:MillisecondsToString footer}}

MillisecondsToString (Float function)

2015-12-28T20:43:55Z

Tbullock: Negative numbers work just fine.

SecondsToString (Float function)

2015-12-28T20:39:54Z

Tbullock: Yea it will take negative numbers.

{{Template:Float:SecondsToString subtitle}}

The <var>SecondsToString</var> [[Intrinsic classes|intrinsic]] function operates on a <var>Float</var> value representing seconds since 1900 and returns a formatted string representing that date/time.

==Syntax==
{{Template:Float:SecondsToString syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th><td>A variable to receive the formatted [[Datetime_string_formats|date/time string]] result of the <var>SecondsToString</var> method.</td></tr>
<tr><th>float</th><td>A <var>Float</var> value representing seconds since 1900. Range -4638816000 - 255611289599.</td></tr>
<tr><th>format</th><td>A valid [[Datetime_string_formats|date/time string format]].</td></tr>
</table>

==Examples==
See the <var>StringToSeconds</var> [[StringToSeconds (String function)#Examples|example]].

==See also==
<ul>
<li>Related intrinsic methods (provide conversion from one form of date representation to another):
<ul>
<li><var>[[DaysToString (Float_function)|DaysToString]]</var>
<li><var>[[MillisecondsToString (Float_function)|MillisecondsToString ]]</var>
<li><var>[[StringToDays (String_function)|StringToDays]]</var>
<li><var>[[StringToMilliseconds (String_function)|StringToMilliseconds]]</var>
<li><var>[[StringToSeconds (String_function)|StringToSeconds]]</var>
<li><var>[[TimeStringConvert (String_function)|TimeStringConvert]]</var>
</ul>
<li>Related <var>System</var> methods:
<ul>
<li><var>[[CurrentTimeMilliseconds (System function)|CurrentTimeMilliseconds]]</var>
<li><var>[[CurrentTimeSeconds (System function)|CurrentTimeSeconds]]</var>
<li><var>[[CurrentTimeDays (System function)|CurrentTimeDays ]]</var>
<li><var>[[CurrentTimeString (System function)|CurrentTimeString ]]</var>
</ul>
</ul>
{{Template:Float:SecondsToString footer}}

WakeupAt (System function)

2015-12-28T20:24:32Z

Tbullock: 12 hour limit

{{Template:System:WakeupAt subtitle}}
The <var>[[WakeupAt (System function)|WakeupAt]]</var> function is an enhanced alternative
as the <var class="product">User Language</var> <var>Pause</var> statement, allowing wakeup time resolution of 1 millisecond,
and returns the current time in milliseconds.
==Syntax==
{{Template:System:WakeupAt syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%number</th><td>The current time, after waking up, in milliseconds.</td></tr>
<tr><th nowrap="true"><var class="nobr">%(System)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>WakeupAt</var> can also be invoked via a <var>System</var> object variable, which may be <var>Null</var>.</td></tr>
<tr><th>timeInMilliseconds</th>
<td>The time, in milliseconds, at which to wake up. May not be more than 12 hours in the future. </td></tr>
</table>

==Examples==
The following code fragment pauses for 1 second at the start of each iteration of the <var>Repeat</var> loop:
%time = %(system):[[CurrentTimeMilliseconds (System function)|currentTimeMilliseconds]]
repeat
%time = %time + 1000
%time = %(system):wakeupAt(%time)


==See also==
{{Template:System:WakeupAt footer}}

LOGWHO command

2015-12-09T20:10:46Z

Tbullock: Leading zeros

==Summary==
<dl>
<dt>Privileges
<dd>System administrator
<dt>Function
<dd>Lists the user IDs of all users who are currently logged in to <var class="product">Model 204</var>
</dl>
==Format==
LOGWHO

==Syntax notes==
LOGWHO can be issued from within a procedure - this has been the case since V6R1, or perhaps longer.

==Example==
LOGWHO
USER 0 SUPERKLUGE
USER 1 CCA CENSUS CARS
USER 3 DPH HEALTH

==Usage notes==
The LOGWHO command lists the user IDs of all users currently logged in to <var class="product">Model 204</var>. LOGWHO also lists each SNA Communications Server (formerly VTAM) terminal that is in session with <var class="product">Model 204</var> even if no user is currently logged in through that thread; in this case, NO ACCOUNT appears in the user ID field of the output.
For each user ID listed, LOGWHO provides a terminal identification field if the SNA Communications Server or IUCV access method is being used by that thread. LOGWHO also displays the names of any files opened by each user ID.

LOGWHO also lists process and processgroup names.

====LOGWHO for PQO====
For Parallel Query Option/204 (PQO) users, the LOGWHO display depends on whether it is issued for a client or server. Issued at a client node, LOGWHO shows the remote files currently open. Issued at a server node for a service thread, the display includes identification of client users and any service thread subsystem.

The format of the PQO display follows. The fields are left-justified and blank-filled, except for nn, the user number, which is right-justified, zero-filled, and in a field of two digits for numbers 0 through 99 or of as many digits necessary for larger numbers. bb is two blanks.
USER nn useridbbtermidbbfile1bbfile2...bb
[CLNT:bbmmmmmbbONbbclntname] [APSY: apsyname]

where: 
<table>

<tr class="head">
<th>Term</th> <th>Thread</th> <th>Meaning</th> </tr>

<tr> <th rowspan="2">
nn
</th> <td>
Client
</td> <td>
User thread number 
</td> </tr>

<tr> <td>
Service
</td> <td>
User thread number of the service thread
</td> </tr>

<tr> <th rowspan="2">
userid
</th> <td>
Client
</td> <td>
User login ID
</td> </tr>

<tr> <td>
Service
</td> <td>
Client user's login ID
</td> </tr>

<tr> <th rowspan="2">
termid
</th> <td>
Client
</td> <td>
User terminal ID or z/VM machine name
</td> </tr>

<tr> <td>
Service
</td> <td>
Client's node name as specified on local DEFINE PROCESSGROUP command REMOTEID parameter
</td> </tr>

<tr> <th rowspan="2">
file1, file2,...
</th> <td>
Client
</td> <td>
Names of any open local files, and
Names of open remote files, using the full remote file specification (filename AT location)
</td> </tr>

<tr> <td>
Service
</td> <td>
Names of any open local files
</td> </tr>

<tr> <th>
mmmmm 
</th> <td>
Service
</td> <td>
User number of the client thread currently using the service thread
</td> </tr>

<tr> <th>
clntname
</th> <td>
Service
</td> <td>
Client User 0 LOCATION parameter value
</td> </tr>

<tr> <th>
apsyname
</th> <td>
Service
</td> <td>
Name of the subsystem into which service thread is logged, if any
</td> </tr>
</table>

In addition to the list of regular user IDs, LOGWHO prints a list of terminal lines that have encountered severe I/O errors and have been shut down (dead users). Also printed is a list of users to be reactivated (hardwired terminals that have been temporarily shut down because of I/O errors and that can be reactivated with the REACTIVATE command).

To execute the LOGWHO command, reply STATUS to the outstanding HALT message.

====Sending LOGWHO output to the USE data set====

If there is an open USE data set, the LOGWHO command output is directed to it. See [[RESET COMMAND command|RESET COMMAND: Control USE data set support]] for a discussion of how to direct the output.
[[Category: System administrator commands]]
[[Category:Commands]]

$X2C

2015-11-17T19:17:12Z

Tbullock: Lower case text really prints lower case

The $X2C function changes a 2-byte character of input into 1-byte hexadecimal-equivalent EBCDIC characters. Called with a character string, $X2C returns a character string that is half as long. The maximum input length is 255 bytes. If the input length is more than 255 bytes or if input contains invalid hexadecimal data, a null string is returned. There is no function to translate 2-byte hexadecimal characters to ASCII characters. 
The output is one half the length of the input. Each pair of hexadecimal characters in the output becomes an EBCDIC character. For example,
C'01' = X'01' or E8C5E2 = 'YES.'
Syntax
The format for the $X2C function is:
$X2C(inputchar)

where inputchar is the input character string (either a %variable or a quoted literal) to be converted to one-byte hexadecimal-equivalent characters.
Input must be an even number of bytes (divisible by 2) and contain only combinations of the following characters:
0123456789ABCDEF

If the input character string is invalid for any reason and cannot be converted, then the output string returned by the function is set to a null.
Example 1
BEGIN
%INPUT_IN_HEX = '05'
%PAD_CHAR = $X2C(%INPUT_IN_HEX)
END

Example 2
BEGIN
PRINT $X2C('C1C2C3')
END

(output is ABC)

Example 3
BEGIN
PRINT $X2C('F1')
END

(output is 1)

Example 4
This example produces a hexadecimal to decimal conversion:
PROCEDURE X2D
B
PRINT $UNBIN($X2C($PAD($READ('X2D enter hex value'),'0',8)))
END
END PROCEDURE

resulting in this output:
$$X2D enter hex value <--- $READ prompt
FC35 <--- User enters some hexadecimal input
64565 <--- Procedure prints output value in Decimal

 
[[Category:SOUL $functions]]

$ItsOpen

2015-11-05T21:19:48Z

Tbullock: That's a data line, not a header

The $ITSOPEN function lets you determine whether a file is open. $ITSOPEN only checks files, not groups of files. The return codes are:
<table>
<tr>
<td>0</td>
<td>the file is not open</td>
</tr>
<tr>
<td>1</td>
<td>the file is open</td>
</tr>
</table>
Syntax
The format for the $ITSOPEN function is:
$ITSOPEN({[FILE] name [AT location] | [PERM | TEMP] [GROUP] name})

where name (optional) is a %variable or a literal name of the file or group. You <var class="term">must</var> enter the filename in uppercase. A file synonym name can also be used. If you do not enter a location (specifying a null argument), <var class="product">Model 204</var> uses the reference context (at compile time) of the statement which calls the function.
Example
BEGIN
%FILE IS STRING LEN 8
%FILE = $READ('ENTER THE FILENAME')
IF $ITSOPEN(%FILE) THEN
PRINT %FILE ' IS OPEN'
ELSE
PRINT %FILE ' IS NOT OPEN'
END

[[Category:SOUL $functions]]

$ItsOpen

2015-11-05T21:14:09Z

Tbullock: needed a length

The $ITSOPEN function lets you determine whether a file is open. $ITSOPEN only checks files, not groups of files. The return codes are: 
<table>
<tr class="head">
<th align="right">0</th>
<th>the file is not open</th>
</tr>
<tr>
<td align="right">1</td>
<td>the file is open </td>
</tr>
</table>
Syntax
The format for the $ITSOPEN function is:
$ITSOPEN({[FILE] name [AT location]

| [PERM | TEMP] [GROUP] name})

where name (optional) is a %variable or a literal name of the file or group. You <var class="term">must</var> enter the filename in uppercase. A file synonym name can also be used. If you do not enter a location (specifying a null argument), <var class="product">Model 204</var> uses the reference context (at compile time) of the statement which calls the function.
Example
BEGIN
%FILE IS STRING LEN 8
%FILE = $READ('ENTER THE FILENAME')
IF $ITSOPEN(%FILE) THEN
PRINT %FILE ' IS OPEN'
ELSE
PRINT %FILE ' IS NOT OPEN'
END

[[Category:SOUL $functions]]

Object variables

2015-10-29T23:16:56Z

Tbullock: '' to avoid italics

An object variable is a proxy or substitute for an object. You do not access or perform actions against an object directly but instead via operations on an object variable that references the object. This page discusses how you
create, work with, and discard object variables.
==Why use an object reference instead of an object==
Object variables are used to declare variables that refer to instances of
a class.
Despite their name, they are not really objects, as such,
but references or pointers to objects.
The underlying objects themselves are never directly accessible and can only
be accessed via an object reference.
This concept of reference variables being used to access underlying objects
is common to all object-oriented languages.
There are two, primary reasons for this:
<ol>
<li>Objects can get quite large, and moving them around an application
rather than moving references around would be extremely expensive.
<li>Objects usually represent some "real world" entity.
To have multiple copies of such an entity in an application creates
the possibility that these copies would get out of synch, causing
application complexity and even bugs.
</ol>

Assignment and comparison operations are
probably the two most significant places to note the distinction between
object variables being references to the objects or the objects themselves.
The following is an example of assignment of an object reference, rather
than an object:

class pet
public
variable type is string len 16
end public
end class
...
%rover is object pet
%fluffy is object pet
...
%rover:type = 'Dog'
%fluffy = %rover
%fluffy:type = 'Cat'
print %rover:type


Because the statement <code>%fluffy = %rover</code> assigns to %fluffy a reference
to the same object as %rover, both variables end up referring
to the same object.
The statement <code>%fluffy:type = 'Cat'</code> therefore changes
the underlying object pointed to by %rover (since it's the same object
as the one pointed to by %fluffy).
As a result, the Print statement prints <code>Cat</code>.

As assignment assigns references, comparison compares references.
That is, a comparison between two object references does not compare the objects
being referred to, but it instead compares whether two object references point to
the same object.

Consider the following example::
class pet
public
variable type is string len 16
end public
end class
...
%rover is object pet
%fluffy is object pet
...
%rover = new
%fluffy = new
%rover:type = 'Dog'
%fluffy:type = 'Dog'
if %fluffy eq %rover then
print 'They''re equal!'
end if


This will not print <code>They're equal</code>.
Even though the objects
pointed to by %fluffy and %rover have the same variable values, they
are different objects, so %fluffy is not equal to %rover.
However, if the code were changed:

class pet
public
variable type is string len 16
end public
end class
...
%rover is object pet
%fluffy is object pet
...
%rover:type = 'Dog'
%rover = %fluffy
if %fluffy eq %rover then
print 'They''re equal!'
end if


<code>They're equal</code> will be printed, because <code>%rover = %fluffy</code>
sets <code>%rover</code> to point to the same object as <code>%fluffy</code>, making them equal.

'''Note:'''
Since order comparisons (GE, LE, GT, and LT) are meaningless for references —
when is a reference to one object greater than a reference to another? —
only equality and inequality (EQ and NE) comparisons are allowed for objects. 

Despite the foregoing remarks, for most purposes, one can still think of
object variables as being
the objects themselves, rather than references to the object.
For example, in the statement:

%rover:type = 'Ferret'


it is quite natural to think of the statement as setting %rover's Type to
"ferret," rather than as setting the type of the object referenced
by %rover to "Ferret."

==Creating object instances==
Since object variables are references to objects, two questions naturally
arise: what object does an object variable refer to initially, and
where does the referenced object come from?
The answer to the first question is that an object variable initially
points to ''no'' object.
So, the following program would cause a request cancellation error:

class pet
public
variable type is string len 16
end public
end class
...
%rover is object pet

%rover:type = 'Dog'


The statement <code>%rover:type = 'Dog'</code> attempts to set the object's
type to "Dog," but there is no instance of an object for
which to set the type.
This kind of error is sometimes referred to as a '''null pointer
exception'''.

So how, then, is an object created?
The answer is via a <var>Constructor</var>, usually the default one named <var>New</var>.

===Using New or other Constructors===
When you invoke a <var>Constructor</var> method, <var class="product">SOUL</var> creates an object instance which is available to the <var>Constructor</var> code. The <var>Constructor</var>:
<ul>
<li>Operates on the new instance (which is the value of <code>%this</code> within the <var>Constructor</var>)
Unlike a shared method, a <var>Constructor</var> operates on an object instance.

<li>Returns the value of <code>%this</code> as the result.

Like a <var>Subroutine</var>, the <var>Constructor</var>'s <var>Return</var> statement may not specify a value, but like a <var>Function</var>, the <var>Constructor</var> does produce a result.
</ul>

In any non-<var>[[Dynamic dispatch#Overridable versus Abstract methods|Abstract]]</var> class, you can invoke a default <var>Constructor</var>, named <var>New</var>, which operates no further on <code>%this</code> and simply returns a new instance for explicit or implicit assignment. As described below, you can explicitly define <var>New</var> to operate on the new instance, you can define other constructors in addition to <var>New</var>, and you can also [[#Private constructors|"disallow"]] <var>New</var> from use outside the class definition.

====Syntax for Constructors====
The syntax for invoking a <var>Constructor</var> is the same as the syntax for
invoking a <var>Shared</var> method which returns an instance of the class.

To invoke the <var>New</var> constructor and assign its result:
%rover = new

You can explicitly indicate the class of the object as follows:
%rover = %(pet):new


While specifying the class in this way is unnecessary and might
be viewed as detrimental because it results in the class name
being sprinkled around inside application code, it might also
be viewed as beneficial — making the object class
clear in the part of code where the object is created.

====Customizing a Constructor====
Sometimes it is useful to run code when creating an instance of a class.
In such cases, you can explicitly define the <var>New</var> <var>Constructor</var>:
class pet
public
variable initTime is float
constructor new
end public
constructor new
%initTime = $sir_datens
end constructor
end class


In the above example, the class variable <code>initTime</code> is set
to the time the instance of the object is created.
That code runs when the <var>New</var> <var>Constructor</var> is invoked in a program to create a <code>pet</code> instance:
%josh is object pet
...
%josh = new


Sometimes it is useful to have a constructor take parameters.
For example, if it doesn't make sense to have a Pet object without
a Type, make the <var>New</var> constructor require an input parameter that
sets the class Type variable:
class pet
public
variable type is string len 16
constructor new(%type is string len 16)
end public
constructor new(%type is string len 16)
%this:type = %type
end constructor
end class


The parameters
must be specified on the <var>New</var> constructor:
%snoopy is object pet
...
%snoopy = new('Beagle')


As of <var class="product">[[Sirius Mods]]</var> Version 7.2,
constructors are allowed to change the object being constructed.
For example, variable <code>ExistingObj</code> assigns
an existing <code>Dachsie</code> object when constructor <code>Newbie</code> is called:
class dachsie
public
...
constructor newbie
...
end public

public shared
variable ExistingObj is object dachsie
end public shared

constructor newbie
%this = %(this):existingObj
end constructor
...
end class


However, this feature was actually provided for a different purpose,
and using it in the context shown above requires caution.
While <code>%this</code> is an input parameter to the <var>Constructor</var>, changing it changes the
object returned to the <var>Constructor</var> invoker, so it acts almost like an output parameter.
Modifying <code>%this</code> within the <var>Constructor</var> can also produce unexpected behavior
if the <var>Constructor</var> is itself called from an [[Inheritance and polymorphism|extension class Construct statement]].

Instead of using a <var>Constructor</var> to return a modified object as in the example
above, you should consider using a [[#Virtual Constructor methods|"factory method"]].

====Other ways to use a Constructor====
A <var>Constructor</var> can also be used in these ways:
<ul>
<li>To specify a new instance of a class as an input parameter to a method:
class pet
public
...
subroutine compare(%pet is object pet)
...
end public
...
end class
...
%lassie is object pet
...
%lassie:compare( new('Collie') )

<li>Without being explicitly specified,
to automatically create an instance of an object
when an object variable is first referenced.
For such instantiation, you must
specify <var>[[Classes and Objects#The Auto keyword on object declarations|Auto New]]</var> in the object's declaration.
</ul>

====Using multiple Constructors====
Most object-oriented languages support only a single constructor name for a class.
If multiple constructors are needed, this is achieved with overloading —
the use of different methods with the same name that are distinguished by
their parameter lists.
Overloading, however, can be confusing, and it is limited: you can't
have multiple methods with the same name and the same datatypes in the
parameter list.

<var class="product">SOUL</var> supports '''multiple constructors''':
class resource
public
constructor newFromUrl(%url is string len 255)
constructor newFromProc(%proc is string len 255)
...
end public
...
end class
...
%res is object resource
...
%res = newFromUrl('http://nfl.com/score')
...
%res = newFromProc('LOCAL.RESOURCE.PROC')
...
%res = new


This example illustrates:
<ul>
<li>Constructors not called New are invoked in exactly the same way
as the <var>New</var> constructor.

A function that invokes a constructor can be used in any other
context in which the <var>New</var> <var>Constructor</var> can be used.
<li>It is recommended that you always begin <var>Constructor</var> names with the
word "New" to distinguish them from other methods.
</ul>

====Private Constructors====
Although this section has discussed only public constructors, that is,
constructors defined for use outside the class definition,
you may also define '''private constructors''',
which may only be invoked from inside the class.
You declare such a <var>Constructor</var> in the <var>Private</var> block of a class definition,
and you define it with your other methods after the declaration blocks.

If you want to define a private constructor named New, however,
you must make sure to specify <code>Disallow New</code>
in the <var>Public</var> block of the class definition (see [[Classes and Objects#Declaration block syntax|"Declaration block
syntax"]]).
No other private constructors require an additional <var>Disallow New</var> in the
<var>Public</var> block.

===Virtual constructors===
It is possible to have a non-constructor shared function return an
instance of a class:

class resource
public shared
function newFromUrl(%url is string len 255) -
is object resource
...
end public shared

function newFromUrl(%url is string len 255) -
is object resource
%return is object resource
print 'In the factory'
%return = new
end function
...
end class
...
%res is object resource
...
%res = %res:newFromUrl('http://nfl.com/score')


Such functions are often called '''factory methods''' or
virtual constructors.
As the example illustrates, two things distinguish factory methods
from constructors:
<ul>
<li>They can run code before the object is instantiated.
<li>They might not actually instantiate an object but return a reference to an existing instance. Such a method may not truly be a factory method.
</ul>
The support for multiple constructors means that <var class="product">SOUL</var>
users need factory methods less than those using
most other object-oriented programming languages.

Virtual constructors can be invoked in much the same way that regular constructors are invoked, that is, without specifying the class name if the class name can be determined from context.
For example, the above example of the NewFromUrl virtual constructor can be changed to the following:

%res is object resource
...
%res = newFromUrl('http://nfl.com/score')


Similarly, if a method called Send in class Coworker took a resource
object as an input parameter, the NewFromUrl virtual constructor could
also be used as follows:

%sufjan is object coworker
...
%sufjan:send(newFromUrl('http://asthmatickitty.com'))


Because the naming rules for virtual constructors are now
identical to that for regular constructors, the two can be used
interchangeably, and one can be changed to the other as requirements
change, without breaking existing applications.

==Object variables within class definitions==
Classes can, themselves, contain object variables:
class pet
public
...
variable owner is object human
...
end public
...
end class


Remember that an object variable is not really the object itself but
a reference to an underlying object so, in the case of an object
variable inside a class block, the class does not contain another
object, per se, but simply a reference to another object.

It is possible for two different classes to each contain references to each other.
But for an object variable to be defined, the object class must already have
been declared.
So if two classes contain references to each other, at least one must
be declared without the references before the other.
The simplest way to do this is with an empty Class block:

class human
end class

class pet
public
...
variable owner is object human
...
end public
...
end class
...
class human
public
...
variable dog is object pet
...
end public
...
end class


It is also possible for a class to contain object variables that
refer to the containing class:
class pet
public
...
variable sibling is object pet
...
end public
...
end class


In such a case, no empty <var>Class</var> block is necessary to declare the class
because the <var>Class</var> block containing the object variable is sufficient
to declare the existence of the class.

==Discarding objects==

The <var>New</var> constructor creates an instance of a class.
This instance is maintained until it is either implicitly or explicitly
discarded (or destroyed in the terminology of some object-oriented languages).
===Discarding explicitly===

An underlying object can be discarded explicitly by invoking the <var>Discard</var>
method (system subroutine) against it:

%mick is object dog
...
%mick = new('Terrier')
...
* Done with object pointed to by %mick
%mick:discard


The Discard method never takes any input parameters and returns no value,
so it is a Subroutine.
The Discard method is an AllowNullObject method because it can be invoked
with a null object, such as one that was never set:

%mick is object dog

for %i from 1 to 10
%mick:discard
...
end for


In the first loop iteration, above, <code>%mick</code> would not be set, so the
<code>%mick:discard</code> call would not have anything to discard,
but it would not indicate a request-cancelling null-pointer error.

<blockquote class="note">
'''Note:''' Not all objects may be discarded explicitly: 
<ul>
<li>Some objects are integral parts of other objects, and discarding one cannot be done without compromising the other. For example, you may not explicitly <var>Discard</var> an XmlNode object, though as discussed [[#xmlnode|below]], you may discard it by using the <var>DeepDiscard</var> method.
<li>Some objects may be explicitly defined with a <var>[[Classes and Objects#Disallow clause|Disallow Discard]]</var> clause, which protects them from being discarded directly.
</ul>
</blockquote>

===Discarding implicitly===
Objects may be discarded implicitly, when there are no
more references to the underlying object.
If there are no references to an underlying object, there is no
way to retrieve or set values in the object or to invoke methods against
the object.
Since there is no reason to maintain the object any more, the
<var class="product">Janus SOAP User Language Interface</var> automatically discards the object.
The following code demonstrates this principle:
%bunny is object dog
...
%bunny = new('Ibizan Hound')
%bunny:show
%bunny:feed
%bunny = new('Yorkshire Terrier')


When the statement <code>%bunny = new('Yorkshire terrier')</code> is executed,
a new object is created, but it is no longer possible to access the object
instantiated by <code>%bunny = new('Ibizan hound')</code> — there are
no longer any references to that object.
Because of that, the first Dog object is automatically discarded when the
second Dog object is created and referenced by <code>%bunny</code>.
If a second reference to that object had been set, it would not have been
discarded:

%bunny is object dog
%dallas is object dog
...
%bunny = new('German Shepherd')
%dallas = %bunny
%bunny:show
%bunny:feed
%bunny = new('Yorkshire terrier')


A reference to an object can be inside another object:

class dog
public
variable name is string len 32
variable breed is string len 32
variable nextCompetitor is object
...
end public
end class
...
%first is object dog
...
%first = new('Josh', 'Newfoundland')
%first:nextCompetitor = new('Mick', 'Kerry Blue Terrier')


In the above example, the object created by
<code>new('Mick', 'Kerry Blue Terrier')</code> can be accessed
via <code>%first:nextCompetitor</code>, so it will not be implicitly
discarded.
In such a way, it is possible to build a chain of objects:

%first is object dog
%last is object dog
%new is object dog
...
%new = new('Josh', 'Newfoundland')
%first = %new
%last = %new
%new = new('Mick', 'Kerry Blue Terrier')
%last:nextCompetitor = %new
%last = %new
%new = new('Les', 'Pekingese')
%last:nextCompetitor = %new
%last = %new
%new = new('Bunny', 'Ibizan Hound')
%last:nextCompetitor = %new
%last = %new


In the above example, the object created by
<code>new('Les', 'Pekingese')</code> can be accessed by
<code>%first:nextCompetitor:nextCompetitor</code>, so it is not implicitly
discarded.

By linking objects in such a way, it is possible to create a wide variety
of object super-structures, including chains, trees, webs, and cycles.
A '''cycle''' is a collection of objects where the objects are linked
in such a way as to form a ring:

%first is object dog
%last is object dog
%new is object dog
...
%new = new('Josh', 'Newfoundland')
%first = %new
%last = %new
%new = new('Mick', 'Kerry Blue Terrier')
%last:nextCompetitor = %new
%last = %new
%new = new('Les', 'Pekingese')
%last:nextCompetitor = %first


A cycle can even be created with a single object:

%new is object dog
...
%new = new('Josh', 'Newfoundland')
%new:nextCompetitor = %new


A web of objects can contain many cycles of objects.

If a cycle of objects is created, each object in the cycle
will always have at least one reference to it — the previous
item in the cycle.
This means that even if all other references to the objects in a cycle
were eliminated, the objects would still not be discarded because they
would each still have a reference to them, even though those references,
themselves, aren't reachable from any variables in the request.
The following illustrates a case where two objects cannot be reached via
any %variable, but they won't be discarded because they reference each other:

%first is object dog
%last is object dog
%new is object dog
...
%first = new('Josh', 'Newfoundland')
%new = new('Mick', 'Kerry Blue Terrier')
%first:nextCompetitor = %new
%new:nextCompetitor = %first
%new = new('Les', 'Pekingese')
%first = %new


Such objects will not be discarded by <var class="product">SOUL</var> until the user logs off.
Most object-oriented languages solve this problem with [[Global and session objects#Managing object storage|garbage collection]] — a process in which all objects are scanned to determine if they are "reachable" from some base variables (in <var class="product">SOUL</var> these would be local and common %variables).

<var class="product">SOUL</var> has a <var>DeepDiscard</var> method, which provides an alternative approach to
some of these cases that is less expensive than garbage collection and simpler than <var>Discard</var>.
<var>DeepDiscard</var> is discussed in the next section.

==Deep discard of objects==
The Discard method ([[Global and session objects#Using system class methods to access global and session objects|Object class]] subroutine) is usually available to explicitly
discard the object referenced by an object variable.
If an object contains a reference to another object (of the same or a
different class), an explicit Discard results in the elimination of the reference.
This removal of the reference can result in an implicit discard of the
reference object, as shown in the following example.

The object referenced by <code>%chain</code> contains
a reference to another object.
When <code>%chain</code> is discarded, the reference to the object with the name
<code>Frack</code> is lost.
Since this is the only reference to that object, the object is then implicitly
discarded.

class linkedList
public
variable name is string len 32
variable next is object linkedList
end public
end class
...
%chain is object linkedList
%chain = new

%chain:name = 'Frick'
%chain:next = new
%chain:next:name = 'Frack'

%chain:discard


Now suppose the class definition remains the same, but the code is changed to
the following:

%chain is object linkedList
%link is object linkedList

%chain = new
%chain:name = 'Frick'
%chain:next = new
%chain:next:name = 'Frack'
%link = %chain:next

%chain:discard


In this case, even when the object referenced by <code>%chain</code> is discarded,
and its reference to the <code>Frack</code> object goes away, there is still a reference to
the <code>Frack</code> object, namely, <code>%link</code>, so that object is not discarded.

<var class="product">SOUL</var> also has a generic '''DeepDiscard''' method:

%obj:DeepDiscard


Like the <var>Discard</var> method, <var>DeepDiscard</var> explicitly discards the method object. But, unlike Discard, it also explicitly discards all objects that are referenced directly or indirectly (a reference to an object that contains a reference to another object, and so on) by the object being discarded. This makes DeepDiscard useful for discarding an entire chain of objects, an object tree, an object cycle, or even an object forest, even if there are still references to some of the objects in the request.

Since <var>DeepDiscard</var> cleans up an object cycle or forest, it is an
efficient alternative to having garbage collection clean these up, if there is
an obvious point in code where the object cycle or forest is no longer used.

Just as with the <var>Discard</var> method, there is a danger with <var>DeepDiscard</var> that
some reference to an explicitly discarded object might still be required.
But because it has a potential to
discard more objects, the risk is somewhat greater with <var>DeepDiscard</var>,
so it should be used with caution.

The <var>DeepDiscard</var> method cannot be used on any object in a class that
<ul>
<li>is declared with a <var>[[Classes and Objects#Disallow clause|Disallow Discard]]</var> clause
<li>contains a reference to a class defined with <var>Disallow Discard</var>
<li>contains an indirect reference to a class that is defined with <var>Disallow Discard</var>
</ul>

Without these rules, an explicit <var>DeepDiscard</var> of an object could result in the explicit discard of an object of a class that expressly disallows explicit discards.

<div id="xmlnode"></div>
For most system classes, <var>DeepDiscard</var> works identically to <var>Discard</var>.
The exceptions to this are:

<ul>
<li><var>Screenfield</var> objects, which you may <var>DeepDiscard</var> but not <var>Discard</var>.
If you <var>DeepDiscard</var> a <var>Screenfield</var>, the underlying <var>Screen</var> object is also discarded.

<li><var>XmlNode</var> objects, which you may <var>DeepDiscard</var> but not <var>Discard</var>.
If you <var>DeepDiscard</var> an <var>XmlNode</var>, the underlying <var>XmlDoc</var> object is also discarded.

<li><var>XmlNodelist</var> objects, which you may <var>Discard</var> or <var>DeepDiscard</var>.
If you <var>Discard</var> an <var>XmlNodelist</var>, the <var>XmlNodelist</var> object (only) is discarded.
If you <var>DeepDiscard</var> an <var>XmlNodelist</var>, both the <var>XmlNodelist</var> object and the
underlying <var>XmlDoc</var> object are discarded.
</ul>

==Working with null valued object variables==
If an object variable does not refer to an object, either because
it was never set, or because the object to which it referred was
discarded, it is considered to have a '''Null''' value.
While, an object variable with a <var>Null</var> value cannot be used as
the object for most methods (except those declared with <var>AllowNullObject</var>),
they can be used in comparisons.

The most common comparison done with objects, in fact, is to test
whether the object is <var>Null</var>:

%first is object dog
%new is object dog
...
%new = new('Josh', 'Newfoundland')
if %first eq null then
%first = new
else
%last:nextCompetitor = %new
end of
%last = new


If a null object variable is compared with another object variable,
it is considered equal if, and only if, the other object variable is
null.

A null object variable can be assigned to another object variable:
%first is object dog
%new is object dog

%new = %first


And a variable can be explicitly set to Null:
%winner is object dog
...
%winner = null


In both comparisons and assignments, <var>Null</var> is actually a shorthand for a [[Shared class members|shared]] null property on the class, and it can be indicated as such:
%winner is object dog
...
%winner = %(dog):null
...
if %winner eq %(dog):null
...

The value <var>Null</var> can also be passed as an input parameter to
a method:
class show
public
...
function score(%entrant is object dog allowNull) -
is float
...
end public
...
end class
...
%winner is object dog
%akc is object show
...
%minScore = %akc:score(null)
...


'''Note:''' Assigning a value to an object property, that is to a Property that
returns an object, is a special case of passing an input parameter to a method.
The value assigned is
an implicit parameter of the <var>Set</var> method of the property.
In such cases, you may validly assign a Null value,
as if the implicit parameter included an implicit AllowNull keyword.


An object that is explicitly discarded causes all references to that
object to become null: 
%first is object dog
%new is object dog

%new = new('Dallas', 'German Shepherd')
%first = %new
%first:discard

In the above example, both <code>%first</code> and <code>%new</code> are
set to <var>Null</var> after the <code>%first:discard</code>.

==Passing object variables as parameters==
Object variables can be passed as method or complex subroutine parameters:
class clown
public
subroutine honk(%nose is object nose)
...
end public
...
end class
...
%bozo is object clown
%schnoz is object nose
...
%bozo:honk(%schnoz)


By default, passing a null object variable as a method or complex subroutine
parameter causes request cancellation.
However, the '''AllowNull''' keyword can be specified as an Input parameter
qualifier in the method or complex subroutine declaration to indicate that
the method or complex subroutine will accept null objects:
class clown
public
subroutine honk(%nose is object nose allowNull)
...
end public
...
end class


An Output object variable is always allowed to be null and can be set
by a method:

class clown
public
subroutine honk(%nose is object nose output)
...
end public
subroutine honk(%nose is object nose output)
%nose = new('red')
end subroutine
...
end class
...
%bozo is object clown
%schnoz is object nose
...
%bozo = new
%bozo:honk(%schnoz)


In this example, <code>%schnoz</code> would be set to reference a new instance of
a <code>nose</code> object that was instantiated by the <code>honk</code> method.

An Input object variable is passed by value to a method
and may be modified within the method.
The method actually receives a copy of a pointer to the object.
The copied pointer may be used to modify the referenced
object, and the
modifications are propagated to the object outside the subroutine.
Changes to the ''pointer'' like assignment or new instantiation,
are allowed, but they are ''not'' propagated to the outer object.

In the example below, the subroutine modifies the <code>%schnoz</code> object color,
but the reassignment to <code>%schnozola</code> does not affect <code>%schnoz</code>:
class clown
public
subroutine honk(%nose is object nose output)
...
property color is string
...
end public

subroutine honk(%nose is object nose output)
%schnozola is object nose
If %clown eq %bozo
'red' = %nose:color
...
%nose = %schnozola
...
end subroutine
...
property color is string
...
end property color
end class
...
%bozo is object clown
%schnoz is object nose
...
%bozo = new
%bozo:honk(%schnoz)


<blockquote class="note">'''Note:''' A case where a method significantly affects the object referenced by
an Input object variable is the Discard method.
A Discard method invoked against an Input parameter sets
the Input parameter and call argument to Null.

This can happen directly:

subroutine honk (%nose is object nose input)

%nose:discard

end subroutine


Or, it can happen indirectly:

subroutine honk (%nose is object nose input)

%beak is object nose

%beak = %nose
%beak:discard

end subroutine

</blockquote>

==See also==
<ul>
<li>[[Classes and Objects]]
<li>[[Copying objects]]
<li>[[Global and session objects]]
<li>[[Managing server space for objects]]
<li>[[Object oriented programming in SOUL]]
</ul>

[[Category:Overviews]]
[[Category:SOUL object-oriented programming topics]]

SetString (System function)

2015-10-23T22:32:40Z

Tbullock: Oops lost the newline.

{{Template:System:SetString subtitle}}
The <var>SetString</var> shared [[Notation conventions for methods#Callable functions|callable]] function sets a [[System class#System and subsystem globals and strings|system-wide string]].

==Syntax==
{{Template:System:SetString syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%number</th><td>A numeric result that indicates whether the string update succeeded. <var class="term">%number</var> is set to 1 upon success. If <var class="term">oldValue</var> is specified and does not match the current setting of the string, the update is not performed and a 0 is returned.</td></tr>

<tr><th><var class="nobr">%(System)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>SetString</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>

<tr><th>name</th>
<td>A string that identifies the global string to be set.</td></tr>

<tr><th>value</th>
<td>A string that identifies the new value for the global string.</td></tr>

<tr><th>oldValue</th>
<td>A string that identifies a value to be compared against the current value of the <var>System</var> string before doing the update. This is an optional argument.</td></tr>
</table>

==Usage notes==
<ul>
<li>All errors result in request cancellation.
<li>It is not an error to set a string that is not set.
<li>Unlike <var>[[SetGlobal_(System_subroutine)#Usage_notes|SetGlobal]]</var>, <var>SetString</var> does not turn off multiprocessing, and it is designed for fairly high levels of updating.
</ul>

==Examples==
<ol>
<li>The following statement sets the system string called <code>DIAMONDS</code>:
%(system):setString('DIAMONDS', 'CLEAR')

<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:
%value is float
%newValue is float

%value = %(system):string('Counter')
%newValue = %value + 1
%(system):setString('Counter', %newValue)

Unfortunately, another thread might update the value of the counter between the time the above code retrieves the value (with <var>[[String_(System_function)|String]]</var>) and the time it updates it (with <var>SetString</var>). In such a case, an increment of the counter might be missed. This is more likely, of course, in an <var class="product">MP/204</var> environment, but you should not count on it being impossible in a non-<var class="product">MP/204</var> environment. To safely update a counter, you can do the following:
%value is float
%newValue is float
%success is float

repeat while not %success
%value = %(system):string('Counter')
%newValue = %value + 1
%success = %(system):setString('Counter', %newValue, %value)
end repeat

If no user has updated <code>Counter</code> between the <var>[[String_(System_function)|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.

While this looks nasty — it seems the code could loop forever — it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.

<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:
%value is longString
%newValue is longString
%myDoc is object xmlDoc
%success is float

repeat while not %success
%value = %(system):string('Complicated')
%myDoc = new
%myDoc:loadXml(%value)
... manipulate myDoc
%newValue = %myDoc:serial(,'EBCDIC')
%success = %(system):setString('Complicated', -
%newValue, %value)
end repeat

Note that the above code assumes that the <code>Complicated</code> system string is already set. If the application cannot guarantee that <code>Complicated</code> has been set, there should be a test for the null string, bypassing the <var>[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]</var> operation and instead populating the <var>XmlDoc</var> with some initial nodes.

The document is stored in the system string in EBCDIC. This is not necessary — the document could be stored in UTF-8 encoding — it is just easier to debug this code if it is saved in EBCDIC.
</ol>

==See also==
{{Template:System:SetString footer}}

SetString (System function)

2015-10-23T22:31:30Z

Tbullock: Align, and make the data types agree.

{{Template:System:SetString subtitle}}
The <var>SetString</var> shared [[Notation conventions for methods#Callable functions|callable]] function sets a [[System class#System and subsystem globals and strings|system-wide string]].

==Syntax==
{{Template:System:SetString syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%number</th><td>A numeric result that indicates whether the string update succeeded. <var class="term">%number</var> is set to 1 upon success. If <var class="term">oldValue</var> is specified and does not match the current setting of the string, the update is not performed and a 0 is returned.</td></tr>

<tr><th><var class="nobr">%(System)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>SetString</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>

<tr><th>name</th>
<td>A string that identifies the global string to be set.</td></tr>

<tr><th>value</th>
<td>A string that identifies the new value for the global string.</td></tr>

<tr><th>oldValue</th>
<td>A string that identifies a value to be compared against the current value of the <var>System</var> string before doing the update. This is an optional argument.</td></tr>
</table>

==Usage notes==
<ul>
<li>All errors result in request cancellation.
<li>It is not an error to set a string that is not set.
<li>Unlike <var>[[SetGlobal_(System_subroutine)#Usage_notes|SetGlobal]]</var>, <var>SetString</var> does not turn off multiprocessing, and it is designed for fairly high levels of updating.
</ul>

==Examples==
<ol>
<li>The following statement sets the system string called <code>DIAMONDS</code>:
%(system):setString('DIAMONDS', 'CLEAR')

<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:
%value is float%newValue is float

%value = %(system):string('Counter')
%newValue = %value + 1
%(system):setString('Counter', %newValue)

Unfortunately, another thread might update the value of the counter between the time the above code retrieves the value (with <var>[[String_(System_function)|String]]</var>) and the time it updates it (with <var>SetString</var>). In such a case, an increment of the counter might be missed. This is more likely, of course, in an <var class="product">MP/204</var> environment, but you should not count on it being impossible in a non-<var class="product">MP/204</var> environment. To safely update a counter, you can do the following:
%value is float
%newValue is float
%success is float

repeat while not %success
%value = %(system):string('Counter')
%newValue = %value + 1
%success = %(system):setString('Counter', %newValue, %value)
end repeat

If no user has updated <code>Counter</code> between the <var>[[String_(System_function)|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.

While this looks nasty — it seems the code could loop forever — it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.

<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:
%value is longString
%newValue is longString
%myDoc is object xmlDoc
%success is float

repeat while not %success
%value = %(system):string('Complicated')
%myDoc = new
%myDoc:loadXml(%value)
... manipulate myDoc
%newValue = %myDoc:serial(,'EBCDIC')
%success = %(system):setString('Complicated', -
%newValue, %value)
end repeat

Note that the above code assumes that the <code>Complicated</code> system string is already set. If the application cannot guarantee that <code>Complicated</code> has been set, there should be a test for the null string, bypassing the <var>[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]</var> operation and instead populating the <var>XmlDoc</var> with some initial nodes.

The document is stored in the system string in EBCDIC. This is not necessary — the document could be stored in UTF-8 encoding — it is just easier to debug this code if it is saved in EBCDIC.
</ol>

==See also==
{{Template:System:SetString footer}}

SetGlobal (Subsystem subroutine)

2015-10-22T23:18:44Z

Tbullock: Needs an output variable too.

{{Template:Subsystem:SetGlobal subtitle}}
The <var>SetGlobal</var> shared subroutine sets a [[Subsystem_class#System_and_subsystem_globals_and_strings|subsystem global]].

==Syntax==
{{Template:Subsystem:SetGlobal syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th><var class="nobr">%(Subsystem)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>SetGlobal</var> can also be invoked via a <var>Subsystem</var> object variable, which may be <var>Null</var>.</td></tr>

<tr><th>name</th>
<td>A string that identifies the global to be set.</td></tr>

<tr><th>value</th>
<td>A string that identifies the new value for the global.</td></tr>
</table>

==Usage notes==
<ul>
<li>All errors result in request cancellation.

<li>It is not an error to set a global that is not set.

<li>The <var>Subsystem</var> class <var>SetGlobal</var> sets the global for the current <var>subsystem</var> context (indicated by <var>[[Context (Subsystem property)|Context]]</var>).

<li>Like <var>[[$Setg_Subsys]]</var>, <var>SetGlobal</var> momentarily turns off multi-processing, so should not be used heavily in an <var class="product">MP/204</var> environment. <var>[[SetString (Subsystem function)|SetString]]</var> does not suffer this limitation and should be used in these situations.
</ul>

==See also==
<ul>
<li>The <var>setGlobal</var> method, in the <var>Subsystem</var> class, performs a function identical to the <var>$Setg_Subsys</var> function. That is, the following two statements are identical:
%(subsystem):setGlobal('PHLEGMATIC', 'STOLID')
%rc = $Setg_Subsys('PHLEGMATIC', 'STOLID')

<li>For more information about subsystem globals, see [[Subsystem class#System and subsystem globals and strings|System and Subsystem globals and strings]].</ul>
{{Template:Subsystem:SetGlobal footer}}

SetGlobal (Subsystem subroutine)

2015-10-22T23:13:43Z

Tbullock: Function not String

{{Template:Subsystem:SetGlobal subtitle}}
The <var>SetGlobal</var> shared subroutine sets a [[Subsystem_class#System_and_subsystem_globals_and_strings|subsystem global]].

==Syntax==
{{Template:Subsystem:SetGlobal syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th><var class="nobr">%(Subsystem)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>SetGlobal</var> can also be invoked via a <var>Subsystem</var> object variable, which may be <var>Null</var>.</td></tr>

<tr><th>name</th>
<td>A string that identifies the global to be set.</td></tr>

<tr><th>value</th>
<td>A string that identifies the new value for the global.</td></tr>
</table>

==Usage notes==
<ul>
<li>All errors result in request cancellation.

<li>It is not an error to set a global that is not set.

<li>The <var>Subsystem</var> class <var>SetGlobal</var> sets the global for the current <var>subsystem</var> context (indicated by <var>[[Context (Subsystem property)|Context]]</var>).

<li>Like <var>[[$Setg_Subsys]]</var>, <var>SetGlobal</var> momentarily turns off multi-processing, so should not be used heavily in an <var class="product">MP/204</var> environment. <var>[[SetString (Subsystem function)|SetString]]</var> does not suffer this limitation and should be used in these situations.
</ul>

==See also==
<ul>
<li>The <var>setGlobal</var> method, in the <var>Subsystem</var> class, performs a function identical to the <var>$Setg_Subsys</var> function. That is, the following two statements are identical:
%(subsystem):setGlobal('PHLEGMATIC', 'STOLID')
$Setg_Subsys('PHLEGMATIC', 'STOLID')

<li>For more information about subsystem globals, see [[Subsystem class#System and subsystem globals and strings|System and Subsystem globals and strings]].</ul>
{{Template:Subsystem:SetGlobal footer}}

ListOfStrings (System function)

2015-10-22T22:15:18Z

Tbullock: Line up nicer

{{Template:System:ListOfStrings subtitle}}
The <var>ListOfStrings</var> shared function returns a <var>[[Stringlist class|Stringlist]]</var> containing information about [[System class#System and subsystem globals and strings|system-wide strings]].

==Syntax==
{{Template:System:ListOfStrings syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%sl</th>
<td>The <var>Stringlist</var> variable that contains the data about the global strings selected according to the pattern in <var class="term">string</var>.</td></tr>

<tr><th><var class="nobr">%(System)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>ListOfStrings</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>

<tr><th>string</th>
<td>An optional identifying string which may include wildcard characters. Descriptions of the global strings whose names match the <var class="term">string</var> pattern are returned to the <var class="term">%sl</var> <var>Stringlist</var>.

This argument defaults to an asterisk (<tt>*</tt>), that is, all global strings, and its eligible wildcard characters are shown below:
<table>
<tr><th>*</th>
<td>Matches any group of 0 or more characters</td></tr>

<tr><th>?</th>
<td>Matches any single character</td></tr>

<tr><th>"</th>
<td>An escape, which means the next character is treated literally, even if it is a double quotation mark (<tt>"</tt>), question mark (<tt>?</tt>), or asterisk (<tt>*</tt>)</td></tr>
</table></td></tr>
</table>

==Usage notes==
<ul>
<li>All errors result in request cancellation.

<li>The items placed on the target <var>Stringlist</var> are put there in no particular order.

<li>The data returned to the <var>Stringlist</var> is in character format with the following contents:
<ul>
<li>Bytes 1-10 — Userid that last set the global.
<li>Bytes 12-28 — Date and time global last set, in YY/MM/DD HH:MI:SS format.
<li>Bytes 30-53 — Subsystem context for global. Null for system strings.
<li>Bytes 54-  — Global name.
</ul>

<li>You can map to an image the information in each <var>Stringlist</var> item (described in the previous bullet) as follows:
image desc
userid is string len 11
dateTime is string len 18
subsystem is string len 24
name is string len 255
end image

Note that the image items are one byte longer than the item lengths indicated in the previous bullet. Those bytes would be blank, so standard trailing-blank stripping for image items will cause that extra blank to be stripped. The above image could then be used to map the entries, as follows:
%sl is object stringList
%i is float

%sl = %(subsystem):listOfStrings
identify image desc
%sl:[[BindImage (Stringlist subroutine)|bindImage]]('DESC')

for %i from 1 to %sl:count
prepare image desc
%sl:[[GetImage (Stringlist subroutine)|getImage]](%i)
print %desc:userid and %desc:dateTime and -
%desc:subsystem and %desc:name
end for
</ul>

==Examples==
The following statement prints the description of all system strings that end in <code>XML</code>:
%(system):listOfStrings('*.XML'):print

==See also==
{{Template:System:ListOfStrings footer}}

CASE command

2015-10-22T00:30:43Z

Tbullock: 2 is the LINEND option.

'''CASE Mixed/Upper command'''

You may issue either of the following commands in the [[Model 204 full-screen editor]]:

; CASE Mixed
: This command indicates that terminal input is accepted “as is,” without translation to uppercase. This is similar to invoking the *LOWER command prior to entering the Full Screen Editor. The second word of this command, “Mixed”, may be abbreviated to any prefix.
; CASE Upper
: This command indicates that terminal input is translated to uppercase. This is similar to invoking the *UPPER command prior to entering the Full Screen Editor. The second word of this command, “Upper”, may be abbreviated to any prefix.

This command will not affect the case translation setting (*UPPER/*LOWER) that was in effect “outside” the editor; that is, when you exit the editor, the case translation will be as it was prior to entering the editor.

In addition to the CASE command, the initial case translation setting within the editor can be automatically set to *LOWER, using the '1' bit of the [[SIREDIT Parameter|SIREDIT parameter]].

Neither the CASE command nor the *UPPER/*LOWER setting affect the input on the editor command line.

The matching of strings (for example, “/subroutine”) can be done in a case-insensitive manner, using the X'20' bit of the [[SIREDIT parameter|SIREDIT parameter]].

[[Category:Editor commands]]

VTYPE parameter

2015-10-22T00:09:51Z

Tbullock: Yep it does. And if you later change VTYPE to STRING you must do VLEN too.

{{Template:VTYPE parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>STRING
<dt>Parameter type
<dd>User
<dt>Where set
<dd>By any user
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V6.1</var> or earlier
</dl>
==Description==
The default %variable type in User Language
VTYPE is a character string parameter. Valid settings of VTYPE are:
<ul>
<li>
FIXED</li>
<li>
FLOAT</li>
<li>
STRING</li>
<li>
UNDEFINED</li>
</ul>
Setting VTYPE to UNDEFINED forces explicit declaration of all %variables.
Setting VTYPE to UNDEFINED will also set VLEN to 0.

[[Category:User parameters]]
[[Category:Parameters]]

Unspace (String function)

2015-08-11T21:39:55Z

Tbullock: Spell 'onr' more better.

{{Template:String:Unspace subtitle}}

The <var>Unspace</var> [[Intrinsic classes|intrinsic]] function removes the whitespace characters from the method object string and it returns the resulting string. Options are available to:
<ul>
<li>Define which character or characters are to be interpreted as whitespace
<li>Remove leading whitespace, trailing whitespace, both, or neither
<li>Collapse to a single whitespace character any sequences of non-leading, non-trailing whitespace</ul>

==Syntax==
{{Template:String:Unspace syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%outString</th>
<td>A variable to receive the string result of the <var>Unspace</var> method.</td></tr>

<tr><th>string</th>
<td>The input method object string</td></tr>

<tr><th><var>Spaces</var></th>
<td><var>Spaces</var> is an optional, [[Notation conventions for methods#Named parameters|name required]], parameter that is a string that specifies the set of characters considered to be whitespace. The default set is the blank space (<code>' '</code>) character.
If you specify multiple <var>Spaces</var> characters, the first character of the string is the replacement space character: a single one of these is substituted for each sequence of one or more non-leading, non-trailing <var>Spaces</var> characters in the method object string.</td></tr>

<tr><th><var>Leading</var></th>
<td><var>Leading</var> is an optional, name required, parameter that is a <var>[[Enumerations#Using_Boolean_enumerations|Boolean Enumeration]]</var> value that specifies whether to strip all leading whitespace characters. The default is <var>True</var>, strip leading whitespace.</td></tr>

<tr><th><var>Trailing</var></th>
<td><var>Trailing</var> is an optional, name required, parameter that is a <var>Boolean</var> enumeration value that specifies whether to strip all trailing whitespace characters. The default is <var>True</var>, strip trailing whitespace.</td></tr>

<tr><th><var>Compress</var></th>
<td><var>Compress</var> is an optional, name required, parameter that is a <var>Boolean</var> enumeration value that specifies whether to collapse each sequence of spaces to a single space. The default is <var>True</var>, collapse such sequences.</td></tr>
</table>

==Usage notes==
<ul>
<li>Duplicate <var>Spaces</var> characters are tolerated and do not affect the result.
<li>Prior to <var class="product">Sirius Mods</var> Version 7.8, <var>Unspace</var> compressed a string consisting entirely of whitespace characters to a single whitespace character. As of Version 7.8 (and also in Version 7.7 maintenance), <var>Unspace</var> converts a string of whitespace characters to a null string. The Version 7.8 result of
printText {~} = X{' ':unspace}X
is:
' ':unspace = XX

<li><var>Unspace</var> is available as of <var class="product">Sirius Mods</var> Version 7.3.
</ul>

==Examples==
The following are example <var>Unspace</var> statements:
%ls is longstring
%ls = ' so me chars '

[[PrintText statement|printText]] {~} = '{%ls:unspace()}'
printText {~} = '{%ls:unspace(Spaces='X ')}'
printText {~} = '{%ls:unspace(Spaces='X')}'
printText {~} = '{%ls:unspace(leading=false)}'
printText {~} = '{%ls:unspace(trailing=false)}'
printText {~} = '{%ls:unspace(compress=false)}'

The results are respectively:
%ls:unspace() = 'so me chars'
%ls:unspace(Spaces='X ') = 'soXmeXchars'
%ls:unspace(Spaces='X') = ' so me chars'
%ls:unspace(leading=false) = ' so me chars'
%ls:unspace(trailing=false) = 'so me chars '
%ls:unspace(compress=false) = 'so me chars'


==See also==
{{Template:String:Unspace footer}}

Deferred update feature

2015-08-06T23:10:47Z

Tbullock: Oops M not G

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL
The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*

If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.
If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 
If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===
SORTIN is the FRV deferred update data set.
Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended:
RECFM=FB
LRECL=24
BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL
The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=1M
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL
The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T23:09:32Z

Tbullock: Oops M not G

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL
The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*

If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.
If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 
If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===
SORTIN is the FRV deferred update data set.
Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended:
RECFM=FB
LRECL=24
BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL
The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=1M
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL
The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T23:07:40Z

Tbullock: Space the JCL

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL
The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*

If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.
If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 
If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===
SORTIN is the FRV deferred update data set.
Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended:
RECFM=FB
LRECL=24
BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL
The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=1M
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL
The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T23:05:17Z

Tbullock: Space the JCL

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL
The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*

If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.
If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 
If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===
SORTIN is the FRV deferred update data set.
Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended:
RECFM=FB
LRECL=24
BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL
The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7M,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=1M
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T23:00:51Z

Tbullock: 3380 LOL

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL
The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*

If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.
If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 
If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===
SORTIN is the FRV deferred update data set.
Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended:
RECFM=FB
LRECL=24
BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:59:19Z

Tbullock: More funny spaced JCL

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL
The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*

If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.
If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 
If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:57:45Z

Tbullock: Clean the JCL

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL
The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=7G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,CCAEXITS,N)
END
/*

Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL

The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.

If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 

If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:53:56Z

Tbullock: Don't need the dot

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB
LRECL=270 BLKSIZE=27998 (1/2 track on a 3390 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL

The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*


Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL

The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.

If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 

If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:52:33Z

Tbullock: Clean up JCL

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL
Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=27998
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB .
LRECL=270 BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL

The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*


Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL

The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.

If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 

If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:48:31Z

Tbullock: Fix JCL errors. 3380 hahaha! Actually the //SORTWKnn datasets are dynamically allocated nowadays...

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=6G,
// PARM='MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=32760)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3390
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3390,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL

Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
// TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3380,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=15476
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB .
LRECL=270 BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL

The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*


Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL

The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.

If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 

If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:41:03Z

Tbullock: LOL 3380

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===
SORTIN is the fixed-length deferred update data set.
Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly.

Recommended DCB subparameters
The following DCB subparameters are recommended:
RECFM=FB
LRECL=24 BLKSIZE=27998 (1/2 track on a 3390 disk)

In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL

Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
// TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3380,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=15476
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB .
LRECL=270 BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL

The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*


Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL

The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.

If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 

If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Deferred update feature

2015-08-06T22:37:47Z

Tbullock: Fix JCL syntax errors

==Overview==

Whenever you change or add a large number of records to a <var class="product">Model 204</var> file, the process can be made more efficient, in terms of execution time, disk I/O, and storage utilization, by deferring the changes or additions that update Tables C and D: updates involving KEY, NUMERIC RANGE, ORDERED, and FRV fields. In the <var class="product">Model 204</var> deferred update feature, the deferred updates to Tables C and D are stored in deferred update data sets while Tables A and B are updated. The deferred updates are then sorted and applied to Tables C and D.

This article describes
<ul>
<li>Basic <var class="product">Model 204</var> deferred update feature</li>
<li>How the feature is implemented</li>
<li>Several different job forms-number of job steps-that the feature can take. </li>
</ul>

When a file is opened in deferred update mode, <var class="product">Model 204</var> protects the file by making it impossible to free the file in that <var class="product">Model 204</var> run. This limitation is necessary to protect the file from being updated before the deferred updates have been applied. All files are closed completely (free) at the end of the <var class="product">Model 204</var> job.

===Deferred update phases===

The two phases of Table updating in a <var class="product">Model 204</var> file during the deferred update process are:
<ul>
<li>Loading Tables A and B and loading the index (Tables C and D) updates into the deferred update data sets</li>
<li>Loading the deferred index updates into Tables C and D</li>
</ul>

===First phase of deferred update===

The first phase of the deferred update process involves executing whatever configuration of <var class="product">Model 204</var> would be run if updates to the index were not being deferred: BATCH204, ONLINE, IFAM1, or IFAM4. Storing new records or changing existing records proceeds normally until the <var class="product">Model 204</var> file is put into deferred update mode by a special form of the OPEN command or the IFOPEN call. Thereafter, only Table A, the internal file dictionary, and Table B, the VISIBLE data, of the file are updated. 

The index information pertaining to FOR EACH VALUE (FRV), KEY, NUMERIC RANGE, and ORDERED retrieval fields is not added directly to Table C and Table D. Instead, it is written to one or two deferred update data sets for processing in later job steps. 
Note: The index update generated by a FILE RECORDS UNDER statement is never deferred.

====Query results between deferred update phases====

For example, suppose that you add the field name = value pair NAME = MURRAY to an existing record in file PEOPLE. PEOPLE is in deferred update mode, and the NAME field is KEY and VISIBLE. If the record is retrieved by some other (preexisting) KEY field, a PRINT NAME statement prints MURRAY, because the field is VISIBLE and is, therefore, stored in Table B. However, the statement FIND ALL RECORDS FOR WHICH NAME = MURRAY does not find the record, because the index information NAME = MURRAY has not yet been added to Tables C and D. 

===Second phase of deferred update===

The second phase of the deferred update process is executed only after the first phase of deferred update process is complete. The second phase of the deferred update process sorts each of the deferred update data sets created in the first phase, then applies the updates to Tables C and D.

Applying the sorted updates from the deferred update data sets adds the information necessary to perform retrievals based on the new KEY, NUMERIC RANGE, and ORDERED retrieval field values. For instance, after applying the deferred updates, the retrieval statement FIND ALL RECORDS FOR WHICH NAME = MURRAY finds the record in the previous example. 

====Additional job steps in a deferred update====

If the file contains FRV (FOR EACH VALUE) fields, applying the deferred index updates to Tables C and D generates an additional deferred update data set. This additional deferred update data set contains more deferred index updates for fields with the FRV (for-each-value) attribute, which must also be sorted, and the sorted deferred updates applied to Tables C and D. 

For example, suppose that the NAME field described previously also has the FRV attribute and that MURRAY is a new value of NAME that has never occurred in any record. The statement FOR EACH VALUE OF NAME does not find the value MURRAY until certain information is added to Tables C and D. This information is contained in the additional deferred update data set.

The procedure for deferring updates to the index normally requires multiple job steps instead of the one job step required if the updates are not deferred. The deferred update feature can use three, five, or seven job steps, depending on the attributes of the fields being deferred and the number of deferred update data sets specified on the OPEN command or the IFOPEN call. The specific job steps required for deferred update processing are described in detail in the section [[#Job steps|Job steps]]. 

==Opening deferred update files==

===Types of deferred update data sets===

There are two forms of deferred update data sets. The OPEN command that places the file in deferred update mode and the attributes of the fields being updated determine whether a fixed-length data set, a variable-length data set, or both are used for the deferred updates. 

===Deferred update OPEN syntax===

The <var>OPEN</var> command and the <var>IFOPEN</var> [[Media:M204 HLIReference V75.pdf|Host Language Interface]] function have special forms that place the file being opened into deferred update mode. In these forms, you can specify one or two deferred update data sets. 
Syntax

The <var>OPEN</var> command syntax in this case is: 

OPEN [FILE] filename,{[dsname1][,dsname2]}


Where:
<ul>
<li><var class="term">filename</var> is the name of the <var class="product">Model 204</var> file to be opened.</li>

<li><var class="term">dsname1</var> is the name of the fixed-length deferred update data set. If <var class="term">dsname1</var> is supplied in the OPEN command, deferred updates to KEY and NUMERIC RANGE fields are written to this data set.</li>

<li><var class="term">dsname2</var> is the name of the variable-length deferred update data set. If dsname2 is supplied in the OPEN command, deferred updates to ORDERED fields are written to this data set. If only <var class="term">dsname2</var> is supplied in the OPEN command, all index updates are written to this data set. If <var class="term">dsname2</var> is not supplied in the OPEN command, updates to ORDERED fields are not deferred. </li>
</ul>

Naming conventions

A deferred update data set must have a name starting with the letters TAPE. It can be placed on either magnetic tape or a direct access device.

For example:
OPEN PEOPLE,TAPEPEOP


To which <var class="product">Model 204</var> responds:
*** M204.0656: UPDATES DEFERRED TO TAPEPEOP


Usage

Use the special form of OPEN only once per main step for a particular file. Subsequent ordinary OPEN commands treat the file as though the already declared deferred update data set(s) were specified.

The maximum number of deferred update files you can have open in a run is 192. If you try to open any more than 192 files, the OPEN fails and <var class="product">Model 204</var> displays the following message:
*** M204.1529: MAXIMUM DEFERRED UPDATE FILES ALREADY OPEN


Space requirements

The space requirements for the deferred update data sets depend on which type of data set is used and the number of KEY, NUMERIC RANGE, or ORDERED retrieval fields that have their index updates deferred during the first phase of the deferred update process.

Example 1: Opening a deferred update file with the first data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the first update data set name, <var class="term">dsname1</var>, specified. The updates to the Ordered Index-the ORDERED fields-are not deferred. The Ordered Index updates are applied during the first phase of the deferred update process:
OPEN CARS,TAPECARF


Example 2: Opening a deferred update file with the second data set specified

In the following example, the CARS file is placed in deferred update mode by using the OPEN command with only the second update data set name, <var class="term">dsname2</var>, specified. Note the two leading commas before the data set name):
OPEN CARS,,TAPECARV


The updates to KEY, NUMERIC RANGE, and ORDERED fields are all deferred to TAPECARV, a variable-length data set.

Example 3: Opening a deferred update file with both data sets specified

Deferring all the updates to the variable-length data set is somewhat less efficient than splitting the updates by providing both deferred update data sets, as in the following example:
OPEN CARS,TAPECARF,TAPECARV


The updates to KEY and NUMERIC RANGE fields are written to the fixed-length data set, TAPECARF, and the updates to ORDERED fields are written to the variable-length data set, TAPECARV.

===Active-defer in deferred update files===

When you open a file in deferred update mode, <var class="product">Model 204</var> places the file in active-defer mode, and the file stays in this mode for the life of the run. The file stays in this mode until the first Z step is successfully completed.

If the file is in active-defer mode, <var class="product">Model 204</var> displays the following error message whenever the file is opened:
*** M204.0624: FILE IS IN DEFERRED UPDATE MODE


However, after the first successful Z step has been run, this message is turned off, whether or not there are still updates to be completed.
==Deferred updates: Phase 1==

The system parameter DUFILES gives the number of files that have been opened in deferred update mode in the current run.) 

After the file is placed in deferred update mode, updates to the file that normally update the index structures are deferred to the deferred update data set(s). These updates can be the result of User Language requests, Host Language Interface functions, or file updating commands. 

===Number of deferred update data sets required===

You must specify at least one deferred update data set in the JCL or FILEDEFs for each file in deferred update mode. If updates are deferred for more than one file in the first phase step, a separate sequence of the remaining second phase steps must be run for each file opened in deferred update mode. (See the seven-, five-, and three-step process descriptions [[#Job steps|Job steps]].)

==Fixed-length deferred update data sets==

The fixed-length data set name corresponds to <var class="term">dsname1</var> in the OPEN command described in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for fixed-length data sets===

The default DCB parameters for the fixed-length data sets are: 
RECFM=FB .
LRECL=24 BLKSIZE=6000 .


For fixed-length deferred update CMS files, the FILEDEF statement must specify "BLOCK 24" for files stored on disk. This results in a blocking factor of one and prevents errors from occurring during checkpointing. 

===Deferred KEY and NUMERIC RANGE field space requirements===

When the updates to KEY and NUMERIC RANGE fields are deferred to the fixed-length data set, the space requirements for the fixed-length deferred update data set are as follows: 
<ul>
<li>For each occurrence of a KEY field that is added or deleted, one 24-byte record is written to the data set. A changed field counts twice; the old value is deleted and the new one is added.</li>

<li>For each occurrence of a NUMERIC RANGE retrieval field that is added or deleted, the average number of 24-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</li>
</ul>

==Variable-length deferred update data sets==

The variable-length data set name corresponds to <var class="term">dsname2</var> discussed in [[#Deferred update OPEN syntax|Deferred update OPEN syntax]]. 

===DCB parameters for variable-length data sets===

The default DCB parameters for the variable-length data sets are: 
RECFM=VB .
LRECL=270 BLKSIZE=6000 .


For z/VSE, set the BLKSIZE parameter with the DEFINE DATASET command. 

You can override the BLKSIZE on the data set or file definition statement. If enough space is available, set BLKSIZE to a full track for most efficient processing. See the description of SPCORE on [[#Setting the SPCORE parameter|Setting the SPCORE parameter]]. 

The length of the variable deferred index update entries is 270.

===Deferring updates to ORDERED fields===

When the updates to ORDERED fields are deferred to the variable-length data set, the space requirements for the variable-length deferred update data set are one record for each occurrence of an ORDERED field that is added or deleted of a length equal to:
15 + the length of the ORDERED field value being added or deleted is written to the data set

Note: The length of an ORDERED NUMERIC deferred numeric value is always 8. The numeric values of an ORDERED NUMERIC field are always stored as FLOAT 8 numbers in the Ordered Index, even if the numbers are stored as FLOAT 16 in Table B. The length of an ORDERED NUMERIC deferred nonnumeric value is the length of the value.

A changed field writes two records: one record to delete the old value and one record to add the new value. 

===Deferring updates to KEY and NUMERIC fields===

When the updates to KEY and NUMERIC range fields, as well as ORDERED fields, are deferred to the variable-length data set, the additional space required in the variable-length deferred update data set is as follows:
<table style="width:80%">
<tr class="head">
<th>For each
occurrence of... </th>
<th>That is added or deleted...</th>
</tr>

<tr>
<td>KEY field </td>
<td>One 28-byte record is written to the data set. A changed field writes two records: one record to delete the old value and one record to add the new value.</td>
</tr>

<tr>
<td nowrap>NUMERIC RANGE retrieval field </td>
<td>

Average number of 28-byte records written is equal to:
4 + (4.5 * the number of digits in the occurrence)
</td>
</tr>
</table>

==Setting the SPCORE parameter==

SPCORE determines how much spare core or unallocated main memory is available after the <var class="product">Model 204</var> program has finished initializing itself. When a <var class="product">Model 204</var> file is first placed into deferred update mode, there must be enough spare core to open the <var class="product">Model 204</var> file and to accommodate the output buffers for each deferred update data set. Each data set requires a spare core of BUFNO*BLKSIZE bytes. 

If more than one deferred update data set is used and/or more than one file goes into deferred update mode, spare core must be large enough to accommodate all the output buffers and associated structures. 
<ul>
<li>Under z/OS, the parameter SPCORE is normally set on User 0's parameter line - the first input line, containing parameter assignments that further define system options and work area sizes. </li>

<li>Under z/VSE, the SIZE parameter is set. </li>

<li>Under z/VM, SPCORE is usually set in the CCAIN input. (See the <var class="book">Rocket Model 204 System Manager's Guide</var> for further explanation.) </li>
</ul>

==Phase 1 sample JCL==

This section presents z/OS and z/VSE JCL examples for the first phase of the deferred update process. The section that include a single z/VM example begins in [[#z/VM deferred update example|z/VM deferred update example]].

The following sequence is an example of the first phase in a deferred update procedure. The file PEOPLE is provided with one fixed-length deferred update data set. The file CARS is provided with two deferred update data sets: one fixed-length deferred update data set and one variable-length deferred update data set.

z/OS example, Phase 1
//JOB UPDATE FILES CARS AND PEOPLE
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204 system
manager to run BATCH204.
//PEOPLE DD DSN=M204.FILE.PEOPLE,DISP=SHR
//TAPEPEOP DD DSN=M204.DEFER.PEOPLE,DISP=(NEW,CATLG),UNIT=TAPE
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//TAPECARF DD DSN=M204.DEFER.FIXED.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//TAPECARV DD DSN=M204.DEFER.VAR.CARS,DISP=(NEW,CATLG),UNIT=TAPE
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*


z/VSE example, Phase 1
// JOB UPDATE FILES CARS AND PEOPLE
// DLBL PEOPLE,'M204.FILE.PEOPLE',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.DEFER.PEOPLE'
// ASSGN SYS015,TAPE
// DLBL CARS,'M204.FILE.CARS'
// EXTENT SYSnnn,volser
// TLBL SYS016,'M204.DEFERF.CARS'
// ASSGN SYS016,TAPE
// TLBL SYS017,'M204.DEFERV.CARS'
// ASSGN SYS017,TAPE
// EXEC BATCH204,SIZE=AUTO
user zero parameters
DEFINE DATASET TAPEPEOP WITH SCOPE=SYSTEM DDNAME=SYS015 -
RECFM=FB LRECL=24 BLKSIZE=6000
DEFINE DATASET TAPECARF LIKE TAPEPEOP WITH DDNAME=SYS016
DEFINE DATASET TAPECARV WITH SCOPE=SYSTEM DDNAME=SYS017 -
RECFM=VB LRECL=270 BLKSIZE=6000
.
.
.
LOGIN userid
password
OPEN PEOPLE,TAPEPEOP
INCLUDE procedure Updating for Tables A and B;
. KEY and NUMERIC RANGE deferred updates
. written to TAPEPEOP. Any Ordered
. Index updates are not deferred.
OPEN CARS,TAPECARF,TAPECARV
INCLUDE procedure Updating for Tables A and B; KEY
. and NUMERIC RANGE deferred updates
. written to TAPECARF. Ordered
. Index updates written to TAPECARV.
CLOSE ALL
EOJ
/*
/&


==Deferred updates: Phase 2==

As many as three data sets might require sorting and application to Tables C and D: 
<ul>
<li>Fixed-length data set</li>
<li>Variable-length data set </li>
<li>FRV (fixed-length) data set</li>
</ul>

Descriptions of processing each of these data sets follow. 

==Sorting the fixed-length deferred update data set==

If you use a fixed-length deferred update data set, it must be sorted by some job step after the first phase step. The fixed-length records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Any sort utility can be used to perform the sort of the fixed-length deferred update data set under z/OS, z/VSE, or z/VM. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate IBM manual for additional information. 
Note: The z/VM SORT command is not adequate if large files are involved, because it lacks the required capacity. 

===SORTIN and SORTOUT data sets===

SORTIN is the fixed-length deferred update data set. 

Specify the SORTOUT DCB parameters as shown in [[#DCB parameters for fixed-length data sets|DCB parameters for fixed-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. 

Recommended DCB subparameters

The following DCB subparameters are recommended: 
RECFM=FB .
LRECL=24 BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the sort program's RECORD statement.

===SORT control statements===

The following SYSIN control statement sorts fixed-length deferred update records in z/OS: 
SORT FIELDS=(1,16,CH,A)


The effect of this statement is to sort the records in ascending order by the first 16 bytes. 

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A)
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the fixed-length deferred update data set===

The amount of space needed for the sort work data sets depends on the number of records in the fixed-length deferred update data set. In general, set the total amount of space in all the SORTWK<var class="term">xx</var> data sets to about twice the number of bytes in the fixed-length deferred update data set that you are sorting. 

For example, suppose that there are 100,000 records in the fixed-length deferred update data set. This is 2,400,000 bytes or about 4 cylinders (rounding up) of a 3380 disk. If you use three sort work data sets for sorting the fixed-length deferred update data set, space parameters of three cylinders apiece yield a total of nine cylinders, or slightly more than twice the size of the fixed-length deferred update data set.

===Sorting the fixed-length deferred update data set===
z/OS JCL

The following z/OS JCL sorts the fixed-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.DEFER.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A)
/*


Many installations provide cataloged procedures that contain most of the previous JCL. 

z/VSE JCL

Following is an example of z/VSE JCL to sort the fixed-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERF.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFIX.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1
. through SORTWKn for
. sort work data sets
.
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
RECORD TYPE=F,LENGTH=24 sort work data sets
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the fixed-length deferred updates==

To apply the fixed-length deferred updates, use the following Z command. The Z command processes the sorted output from the sort of the fixed-length deferred update data set and adds the KEY and NUMERIC RANGE retrieval index information to Tables C and D. If any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. For more information about the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

===Z command===

The Z command has no arguments. It does the following:
<ul>
<li>Reads records from the data set pointed to by the SORT5 data set or file definition statement</li>

<li>Updates Tables C and D of the currently open <var class="product">Model 204</var> file.</li>

<li>Writes FRV deferred update records to the data set pointed to by the TAPE5 data set or file definition statement. </li>
</ul>

When Z command processing is complete, the following statistics are printed, which reflect the changes that occurred during processing:
<table style="width:80%">
<tr class="head">
<th>Statistic</th>
<th>Number of...</th>
</tr>

<tr>
<td>ADDED</td>
<td>Field name=value pairs added to the hashed index. </td>
</tr>

<tr>
<td>DISTINCT</td>
<td>New field name = value pairs added to hashed index fields; or, when processing the FRV deferred update data set, the number of FRV fields updated.</td>
</tr>

<tr>
<td>DELETED</td>
<td>Field name = value pairs deleted from the hashed index.</td>
</tr>

<tr>
<td>FRV</td>
<td>FRV deferred update records written out to the data set pointed to by the TAPE5 data set or file definition statement.</td>
</tr>

<tr>
<td>OI ADDED</td>
<td>Entries added to the Ordered Index.</td>
</tr>

<tr>
<td nowrap>OI DELETED</td>
<td>Entries deleted from the Ordered Index.</td>
</tr>
</table>

===SPCORE parameter===

The SPCORE parameter must be set large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 as well as other associated structures. 

==Fixed-length data set examples==
z/OS JCL

Applying the fixed-length deferred index updates for z/OS follows:
// EXEC ... Include the basic JCL or cataloged
procedure call provided by the
Model 204 system manager to run BATCH204
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FIXED.CARS,
// DISP=(OLD,DELETE,KEEP)
// TAPE5 DD DSN=M204.TAPE5.CARS,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3380,SPACE=(TRK,(5,2)),
// DCB=BLKSIZE=15476
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

Applying the fixed-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFIX.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.CARS',0
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==Sorting the variable-length deferred update data set==

===Variable-length sort keys===

When you use a variable-length deferred update data set, it must be sorted by a job step after the deferred data set first phase. The variable-length records can vary in length from 16 to 270 and must be sorted into ascending order. Unlike fixed-length deferred update records, which contain a fixed-length sort key, variable-length deferred update records for ORDERED fields contain a variable-length sort key. 

Because no standard sort program supports variable-length sort keys, two sort exits are provided to transform the variable-length sort keys into fixed-length sort keys. Transforming variable-length sort keys is done in the E15 sort exit. The E15 sort exit expands variable-length ORDERED deferred update records into fixed-length records. 

This process produces longer sort records, which can increase the time and resources required to produce sorted output. Because sorting performance is quite sensitive to record length, be sure to set the expanded length as part of setting up sort control statements (see [[#SORT control statements|SORT control statements]]).

===Sort utilities===

Any sort utility that supports sorting variable-length records and the use of the E15 and E35 sort exits can be used to perform the sort. The basic JCL for the IBM SORT Utility is described in the following paragraphs. Refer to the appropriate sort utility manual for additional information. 

The z/VM SORT command cannot be used, because it cannot accommodate sort exits. 

===Required sort JCL and EXEC statements===

When writing JCL or z/VM EXECs for sorting, use the following statements:
<ul>
<li>SORTIN is the variable-length deferred update data set.</li>

<li>Specify the SORTOUT DCB parameters as shown in the first phase step on [[#DCB parameters for variable-length data sets|DCB parameters for variable-length data sets]]. In z/OS and z/VM, set DCB subparameters explicitly. </li>

<li>Use the following DCB subparameters:
RECFM=VB .
LRECL=270 BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, specify the physical record format for the SORTIN data set using the SORT program's RECORD statement. 
</li>

<li>Specify CCAPRINT (SYSLST in z/VSE) in the step that sorts the variable-length deferred update data set. CCAPRINT is the <var class="term">ddname</var>, FILEDEF, or DLBL that points to the sort error message output data set. </li>

<li>Specify CCAIN in the step that sorts the variable-length deferred update data set. CCAIN must contain the sort control statements. SYSIN and CCAIN must point to copies of the same sort control statements.

In z/VSE, the CCAIN DLBL is not needed when sorting the variable-length deferred update data set.
</li>

<li>CCAEXITS, the <var class="term">ddname</var> of the library containing the sort exits, is used only in the z/OS environment. For information on installing the sort exits, see the Rocket <var>Model 204 installation guide</var> for your operating system.</li>
</ul>

===SORT control statements===
For z/OS and z/VM

The syntax of SORT control statements is sort-package and operating-system specific, the following example of a SYSIN control statement is applicable for z/OS and z/VM:

Syntax for z/OS and z/VM
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS E15=(OI15xxx,1800),E35=(OI35xxx,1300)
END


Where:
<ul>
<li><var class="term">aa</var> is the sort field length, the value of (<var class="term">vl</var> - 5). It represents the length of the entire data portion of the expanded sort record.</li>

<li><var class="term">vl</var> is a length parameter. See [[#Setting the variable-length sort parameter (vl)|Setting the variable-length sort parameter (vl)]]. The length of the variable deferred index update entries is 270.</li>

<li><var class="term">xxx</var> is OS for z/OS or CMS for z/VM, depending on the operating system.</li>
</ul>

The exact syntax for the MODS statement is operating-system and sort-package dependent.

Syntax for z/VSE
SORT FIELDS=(5,aa,CH,A)
RECORD TYPE=V,LENGTH=(270,vl,270,vl)
MODS PH1=(OI15,1800),PH3=(OI35,1300)
END


==Setting the variable-length sort parameter (vl)==

Because deferred update records of unequal length cannot be properly compared, the sort exit adjusts the variable-length deferred update records to a specified length. That length is the variable-length sort parameter, <var class="term">vl</var>. 

The <var class="term">vl</var> setting determines the number of records in the deferred update data set that are optimally ordered by the sort for loading ordered fields by the Z command. A record whose length is less than the specified setting for vl is sorted into an optimum loading order. Records whose length is greater than or equal to <var class="term">vl</var> are placed in the sorted deferred update data set but not in an optimum loading order.

===Finding the optimum loading order===

It is usually best to place all deferred update records in optimum loading order. If ORDERED fields and either KEY or NUMERIC RANGE fields exist on the same deferred update data set, specify <var class="term">vl</var> as:
vl = A or B, whichever is greater.


where:
<table>
<tr class="head">
<th>This value</th>
<th>Equals...</th>
</tr>

<tr>
<td>A </td>
<td>Length of the longest Ordered Index deferred update record + 1. Estimate this as the length of the longest ORDERED field + 16 bytes overhead.</td>
</tr>

<tr>
<td>B </td>
<td>28 bytes for Hashed Index (KEY or NUMERIC RANGE fields) deferred update records.</td>
</tr>
</table>

====Measuring the longest record====

Determining the exact length of the longest deferred update record requires examining the contents of the variable-length deferred update data sets. This examination is done for you if the File Load utility is being used, as the FILELOAD and FLOD commands print statistics that list the lengths of the deferred update records in the form of a histogram. Record lengths can also be obtained through a user-written program or a utility such as SYNCSORT's HISTOGRAM to read the records in the deferred update data set and determine the longest record. 

===Setting vl for extreme cases===

Specifying <var class="term">vl</var> as described in the previous section results in a sorted deferred update data set that is completely ordered for the most efficient loading by the Z command. In some extreme cases, sorting to completely order all deferred update records places excessive demands on the sorting process because of the way the length is increased for the records to be sorted. 

Typically these cases involve very large files with unusual distributions of record lengths in the deferred update data set as shown in [[#Setting vl example|Setting vl example]]. In these cases, a smaller setting of the vl parameter than previously recommended might be desired, even though this results in a less than complete ordering of the data set. The consequent slowing of the Z command processing must be weighed against the benefit to the sort performance.

Note: In all cases, if a KEY or NUMERIC RANGE field is deferred in the variable-length deferred update data set, vl must be greater than 28. Rocket Software suggests that you reorganize any file that was loaded with a vl of less than 28.

===Setting vl to optimize performance===

Sort performance is sensitive to the effective length (approximately, the product of the number of records and the <var class="term">vl</var> parameter) of the data set to be sorted, falling as the effective length increases. The <var class="term">vl</var> setting that optimizes sort performance minimizes the data set's effective length. Simply lowering <var class="term">vl</var> to minimize effective length might not succeed, however. 

Setting <var class="term">vl</var> greater than or equal to the longest deferred update record length causes each update record to be lengthened to this setting. Sort performance is hampered, because the effective length of the sort data set is increased. 

Setting <var class="term">vl</var> less than the longest deferred update record length causes records whose length is greater than or equal to <var class="term">vl</var> to be spanned: broken into multiple sort records of length <var class="term">vl</var> by the E15 sort exit. These additional sort records are added to the "number of records" factor of the effective length of the sort data set, and might offset the reduction to the effective length from a lower <var class="term">vl</var>. Furthermore, after a record is spanned, it sorts to the end of the sorted data set, reducing the efficiency of the subsequent index loading by the Z command. 

===Setting vl example===

The goal in setting <var class="term">vl</var>, therefore, is to make <var class="term">vl</var> as small as possible while spanning as few records as possible. For example, suppose that the variable-length deferred update data set containing ORDERED field updates consists of the following distribution of record lengths and records by the histogram produced by the FLOD command:
LONGEST DEFERRED UPDATE LRECL=190
RANGE OF LRECL NUMBER OF RECORDS
256-270 0
240-255 0
224-239 0
208-223 0
192-207 0
176-191 5
160-175 0
144-159 0
128-143 0
112-127 0
96-111 15
80- 95 80
64- 79 0
48- 63 2400000
32- 47 400000
1- 31 0


The size of the longest record is 190, but this is not a very satisfactory choice for the <var class="term">vl</var> parameter. The distribution is such that choosing a lower <var class="term">vl</var> produces a significant decrease in the data set's effective length without adding a significant number of spanned records. The most efficient choice for <var class="term">vl</var> here is 64. A large gain in sort performance is purchased at the expense of the relatively few records in the data set that do not get ordered.

==Sort work data sets==

The space needed for the sort work data sets depends on:
<ul>
<li>Sort program used</li>
<li>Number of records in the variable-length deferred update data set</li>
<li>Value of <var class="term">vl</var>. </li>
</ul>

For example, for IBM's DFSORT the recommended sum of the sizes of all the SORTWK<var class="term">xx</var> data sets is:
2 * (number of records to be sorted) * vl


or:
2 * (effective length of sort data set)


The number of records to be sorted is approximately the number of records in the variable-length deferred update data set plus the number of spanned records.

In the example above, with 2,800,100 records in the variable-length deferred update data set, if <var class="term">vl</var> is set to 64, the effective length of the data set to be sorted is: 
(2800000 + (2.∗80) + (2∗15) + (3∗5)).∗ 64 = 123,215,040


This is about 174 cylinders (rounding up) of a 3380 disk. If you use 3 sort work data sets for sorting the variable-length deferred update data set, space parameters of 116 cylinders apiece yield a total of 348 cylinders, two times the effective length of the sort data set. 

===Installing sort exits===

For a detailed discussion of the installation and use of sort exits, consult the sort manuals for the sort program to be used, and also see the Rocket <var class="product">Model 204</var> installation guide for your operating system.

==Variable-length data set examples==

The following examples assume that the sort exit modules or z/VM TEXT files have been given the names OI15<var class="term">xxx</var> and OI35<var class="term">xxx</var>, where <var class="term">xxx</var> is either OS for z/OS or CMS for z/VM, depending on the operating system. 

z/OS JCL

The following z/OS JCL sorts the variable-length deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//CCAPRINT DD SYSOUT=A
//CCAEXITS DD DSN=M204.LINKLIB,DISP=SHR
//SORTIN DD DSN=M204.DEFER.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=VB,LRECL=270,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,3,,CONTIG),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,3,,CONTIG),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//CCAIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*
//SYSIN DD *
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15=(OI15OS,1800,CCAEXITS,N),E35=(OI35OS,1300,
CCAEXITS,N)
END
/*


Many installations provide cataloged procedures that contain most of the above JCL. Check the sort package documentation for the definitive forms of the sort control statements necessary at your installation.

z/VSE JCL

The following z/VSE JCL sorts the variable-length deferred update data set:
// TLBL SORTIN1,'M204.DEFERV.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTVAR.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// DLBL M204CL,'M204.CORE.IMAGE.LIBRARY'
// LIBDEF CL,SEARCH=M204CL
// EXEC SORT,SIZE=(AUTO,100K)
SORT FIELDS=(5,75,CH,A),WORK=n n is number of sort
work data sets
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS PH1=(OI15,L2000,E15),PH3=(OI35,L1000,E35)
INPFIL BLKSIZE=6000
OUTFIL BLKSIZE=6000
/*
/&


==Applying the variable-length deferred updates==

Apply the variable-length deferred updates, using the [[#Z command|Z command]].

The Z command:
<ul>
<li>Processes the sorted output from the sort of the variable-length deferred update data set</li>

<li>Adds the Ordered Index information to Table D. </li>

<li>If any KEY and/or NUMERIC RANGE deferred update records are also in the variable-length deferred update data set, the Z command adds this KEY and/or NUMERIC RANGE retrieval index information to Tables C and D. </li>

<li>If there are KEY field updates in the variable-length deferred update data set, and any of the KEY fields updated also have the FRV attribute, the Z command creates an additional deferred update data set, an FRV data set, that is processed in later job steps. </li>
</ul>

For more information on the FRV deferred update data set, see [[#Applying the FRV deferred updates|Applying the FRV deferred updates]]. 

z/OS JCL

The JCL to apply the variable-length deferred index updates for z/OS follows:
// EXEC ... Include here the basic JCL
or cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.VAR.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


If both a fixed- and a variable-length data set are supplied for the deferred updates, then TAPE5 is not used when applying the variable-length updates and should point to a dummy data set when applying the variable-length updates.

If a fixed-length deferred update data set exists, the FRV deferred updates are generated when the fixed-length deferred updates are applied. 

If only a variable-length data set is supplied for the deferred updates, and any FRV fields are updated during the first phase step, then an FRV deferred update data set must be provided with the TAPE5 <var class="term">ddname</var> so that <var class="product">Model 204</var> can write out the FRV deferred updates to this data set.

z/VSE JCL

The JCL to apply the variable-length deferred index updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTVAR.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM DDNAME=SYS015-
RECFM=VB LRECL=270 BLKSIZE=6000
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==FRV deferred update data set==

The FRV (For Each Value) deferred update data set is very similar to a fixed-length deferred update data set. One 24-byte record is written to the FRV deferred update data set for every new value of an FRV field that is stored in Tables C and D during the Z command processing. Unless the <var class="product">Model 204</var> file being updated has many FRV fields or an FRV field is also MANY-VALUED, the FRV deferred update data set is fairly small. 

===Determining the FRV step===

The number and type of deferred update data sets specified in the OPEN command or IFOPEN call in the first phase of deferred data set processing determines when the FRV defined data set is generated.

If a fixed-length deferred update data set was specified on the OPEN command or IFOPEN call in the first phase step, and an FRV field was updated, the FRV deferred update data set is generated when the fixed-length deferred updates are applied (in other words, during the execution of the Z command that applies the fixed-length deferred updates). 

If no fixed-length deferred update data set was specified in the OPEN command or IFOPEN call, but a variable-length deferred update data set was specified, and an FRV field was updated, the FRV deferred update data set is generated when the variable-length deferred updates are applied-in other words, during the execution of the Z command that applies the variable-length deferred updates. 

===Creating the FRV deferred update data set===

The FRV deferred update data set is always named TAPE5. It can be placed either on magnetic tape or on a direct access device.

DCB parameters

The default parameters are:
RECFM=FB
LRECL=24
BLKSIZE=6000


For z/VSE installations, TAPE5 must be allocated. Under z/OS, no additional action regarding TAPE5 need be taken.

You can specify the BLKSIZE subparameter explicitly. A full disk track is recommended. z/VSE users can specify TAPE5's block size using the DEFINE DATASET command. 

===Sorting the FRV deferred update data set===

The FRV deferred update data set is sorted after the step that created the FRV deferred update data set. The FRV deferred update records are 24 bytes long and must be sorted in ascending order by the first 16 bytes using the standard EBCDIC collating sequence.

Determine the number of records in the FRV deferred update data set by checking statistics of the Z command that created the FRV deferred update data set. The FRV statistic records the number of FRV deferred update records written to the FRV deferred update data set. 

Any sort utility can be used to perform the sort of the FRV deferred update data set. The basic JCL for the IBM SORT Utility follows. Refer to the appropriate IBM manual for additional information.

===SORTIN and SORTOUT===

SORTIN is the FRV deferred update data set.

Specify SORTOUT in the same way as in the step in which it was created. In z/OS and z/VM, set DCB subparameters explicitly. The following DCB subparameters are recommended: 
RECFM=FB
LRECL=24
BLKSIZE=15476 (1/3 track on a 3380 disk)


In z/VSE, the physical record format for the SORTIN data set is specified using the SORT program's RECORD statement.

===SORT control statement examples===

The following SYSIN control statement example sorts FRV deferred update records in z/OS: 

z/OS
SORT FIELDS=(1,16,CH,A),SIZE=E<var class="term">n</var>


where:

<var class="term">n</var> is the value of the FRV statistic taken from the output of the Z command that created the FRV deferred update data set. 
z/VSE

For z/VSE, the SYSIPT control statement is as follows: 
SORT FIELDS=(1,16,CH,A),SIZE=En
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=blocksize of SORTIN
OUTFIL BLKSIZE=blocksize of SORTOUT


===Sort work data sets for the FRV deferred update data set===

The amount of space needed for the sort work data sets for the FRV deferred update data set is calculated in the same way as for the sort work data sets for the fixed-length deferred update data set. See [[#Sort work data sets for the fixed-length deferred update data set|Sort work data sets for the fixed-length deferred update data set]]. 

z/OS JCL

The following z/OS JCL sorts the FRV deferred update data set:
//SORT EXEC PGM=SORT,TIME=60,
// REGION=200K,
// PARM'MSG=AP,CORE=150000'
//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR
//SORTMSGS DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTIN DD DSN=M204.TAPE5.CARS,
// DISP=(OLD,DELETE,KEEP)
//SORTOUT DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(NEW,CATLG,DELETE),UNIT=TAPE,
// DCB=(RECFM=FB,LRECL=24,BLKSIZE=15476)
//SORTWK01 DD SPACE=(CYL,1),
// UNIT=3380
//SORTWK02 DD SPACE=(CYL,1),
// UNIT=(3380,SEP=SORTWK01)
//SORTWK03 DD SPACE=(CYL,1),
// UNIT=(3380,(SEP=SORTWK01,SORTWK02))
//SYSIN DD *
SORT FIELDS=(1,16,CH,A),SIZE=E100
/*


Many sites provide cataloged procedures that contain most of the above JCL.

z/VSE JCL

The following z/VSE JCL sorts the FRV deferred update data set:
// TLBL SORTIN1,'M204.TAPE5.CARS'
// ASSGN SYS002,TAPE
// TLBL SORTOUT,'M204.SORTFRV.CARS'
// ASSGN SYS001,TAPE
sort work statements Specify SORTWK1 through
. SORTWKn for sort work
. data sets
.
// EXEC SORT,SIZE=100K
SORT FIELDS=(1,16,CH,A),WORK=n n is number of
sort work data sets
RECORD TYPE=F,LENGTH=24
INPFIL BLKSIZE=1680
OUTFIL BLKSIZE=1680
/*
/&


==Applying the FRV deferred updates==

To apply the FRV deferred updates, use the [[#Z command|Z command]].
The Z command:
<ul>
<li>Processes the sorted output from the sort of the FRV deferred update data set</li>
<li>Adds the FRV retrieval index information to Tables C and D. </li>
</ul>

Applying the FRV deferred updates is much like applying the fixed-length deferred updates, except that:
<ul>
<li>SORT5 points to the sorted FRV deferred update data set.</li>
<li>TAPE5, under z/OS, points to a dummy data set that has DCB=BLKSIZE=24. Under z/VM, TAPE5 is a dummy file; under z/VSE, it must not be a dummy file. </li>
</ul>

SPCORE

Set the SPCORE parameter large enough to open the <var class="product">Model 204</var> file and to accommodate both the input buffer for SORT5 and the output buffer for TAPE5 along with other structures. See [[#Setting the SPCORE parameter|Setting the SPCORE parameter]].

z/OS JCL

The z/OS JCL to apply the FRV deferred updates for z/OS follows:
// EXEC ... Include here the basic JCL or
cataloged procedure invocation
provided by the Model 204
system manager to run BATCH204.
//CARS DD DSN=M204.FILE.CARS,DISP=SHR
//SORT5 DD DSN=M204.SORTOUT.FRV.CARS,
// DISP=(OLD,DELETE,KEEP)
//TAPE5 DD DUMMY,DCB=BLKSIZE=24
TAPE5 points to a dummy data set
because no new FRV deferred
updates will be created.
//CCAIN DD *
user zero parameters
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*


z/VSE JCL

The z/VSE JCL to apply the FRV deferred updates for z/VSE follows:
// DLBL CARS,'M204.FILE.CARS',,DA
// EXTENT SYSnnn,volser
// TLBL SYS015,'M204.SORTFRV.CARS'
// ASSGN SYS015,TAPE
// DLBL TAPE5,'M204.TAPE5.DUMMY'
// EXTENT SYSnnn,volser
TAPE5 is not used because
no new FRV deferred updates
will be created.
// EXEC BATCH204,SIZE=AUTO
PAGESZ=6184,MAXBUF=20
DEFINE DATASET TAPE5 WITH SCOPE=SYSTEM -
RECFM=FB LRECL=24 BLKSIZE=1680
DEFINE DATASET SORT5 WITH SCOPE=SYSTEM -
DDNAME=SYS015 RECFM=FB LRECL=24 BLKSIZE=1680
LOGIN userid
password
OPEN CARS
Z
CLOSE ALL
EOJ
/*
/&


==z/VM deferred update example==

===Using deferred updates with FASTLOAD to load files===

The most common use of the deferred update feature is to load files. The z/VM FASTLOAD driver EXEC, distributed with the <var class="product">Model 204</var> installation, incorporates the deferred update procedure into the file loading process. The FASTLOAD EXEC can initiate a multistep deferred update procedure that is as many job-steps (seven, five, three, or one) as required. 

The FASTLOAD EXEC accepts as parameters the name of another EXEC, such as DEFUPD in the following example, and the type (number of deferred update procedure job steps) of FASTLOAD to execute. DEFUPD EXEC is used by the driver to define the files to be used for each FASTLOAD step and to invoke <var class="product">Model 204</var> when necessary. 

===FASTLOAD EXEC format===

The format of the FASTLOAD command is:

Syntax
FASTLOAD [TEST] [NODCSS] EXECname [NUM] [(option[)]]


If no option is specified, 5STEP is the default.

where:
<ul>
<li>TEST specifies a test version of the <var class="product">Model 204</var> ONLINE module or shared segment-that is, T204. If TEST is not specified, the production version-that is, M204 is invoked.</li>

<li>NODCSS specifies that shared segments are not to be used, even though they exist.</li>

<li><var class="term">EXECname</var> specifies the name of an EXEC procedure that provides the file definitions and other logic required to prepare a deferred update or File Load utility job. The EXEC procedure is invoked once before each step of the deferred update process, and during FASTLOAD command initialization.</li>

<li>NUM specifies the number, from 1 through 7, of the step to begin with in case of a restart.</li>

<li><var class="term">option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Indicates...</th>
</tr>

<tr>
<td>7STEP </td>
<td>Seven-step job </td>
</tr>

<tr>
<td>5STEP</td>
<td>Five-step job</td>
</tr>

<tr>
<td>3STEP</td>
<td>Three-step job</td>
</tr>

<tr>
<td>1STEP</td>
<td>One-step job</td>
</tr>
</table></li>
</ul>

Setting parameters in the FASTLOAD EXEC

Parameters required to invoke <var class="product">Model 204</var> are set in the EXEC procedure called by the FASTLOAD EXEC. These parameters must be placed in the stack using the &STACK command as keyword-value pairs, separated by blanks, during Steps 1, 3, 5, and 7. The only operand provided to the EXEC called by the FASTLOAD EXEC is the step number.

===FASTLOAD EXEC example===

In the following example, the FASTLOAD EXEC calls DEFUPD and passes it the parameter for the step number to be executed. The DEFUPD EXEC concatenates the passed parameter (&1, for example) with the step name (FLOAD) in a &GOTO statement. This numbering and consequent program flow simulate the job steps in the previous z/OS and z/VSE examples.

z/VM EXEC

Enter the following command to run the example:
FASTLOAD DEFUPD (7STEP


The DEFUPD EXEC appears below, followed by a step-by-step explanation of the EXEC and the files defined in each step.
&CONTROL OFF
&ERROR &EXIT &RETCODE

&IF &1 EQ 0 &GOTO -ACCESS
FILEDEF * CLEAR
&GOTO -FLOAD&1

-ACCESS
RELEASE M
ACCESS 201 M
&EXIT

-FLOAD1
FILEDEF TAPECARF TAP1 SL ( BLOCK 2400 LRECL 24 RECFM FB
LABELDEF TAPECARF VOLID 123456
FILEDEF TAPECARV DISK CARS DEFV W (BLOCK 6000 LRECL 270 RECFM VB
FILEDEF CARS M DSN M204DB CARS
FILEDEF CCAIN DISK DEFUPD CCAIN1 *
&GOTO -COMMON

-FLOAD2
LABELDEF SORTIN1 VOLID 123456
SSORT TAP1 CARS DEFSORT W DEFUPDF SORTCTRL B
&EXIT &RC

-FLOAD3
FILEDEF SORT5 DISK CARS DEFSORT W
FILEDEF TAPE5 DISK CARS FRV W ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN3 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD4
FILEDEF CCAIN DISK DEFUPDV SORTCTRL B
FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
SSORT CARS DEFV W CARS SORTVAR W DEFUPDV SORTCTRL B
&EXIT &RC

-FLOAD5
FILEDEF SORT5 DISK CARS SORTVAR W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB)
FILEDEF CCAIN DISK DEFUPD CCAIN5 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON

-FLOAD6
SSORT CARS FRV W CARS FRVSORT W FASTLOAD SORTCTRL C
&EXIT &RC

-FLOAD7
FILEDEF SORT5 DISK CARS FRVSORT W
FILEDEF TAPE5 DUMMY ( BLOCK 24 LRECL 24 RECFM FB
FILEDEF CCAIN DISK DEFUPD CCAIN7 *
FILEDEF CARS M DSN M204DB CARS
&GOTO -COMMON
&EXIT

-COMMON

FILEDEF CCAPRINT DISK DEFUPD&1 CCAPRINT A
FILEDEF CCAAUDIT DISK DEFUPD&1 CCAAUDIT A
FILEDEF CCATEMP N DSN WORK CCATEMP
FILEDEF CCASTAT N DSN WORK CCASTAT
FILEDEF CCASNAP PRINTER
&STACK SYSOPT 128
&EXIT


===Description of steps===

The task performed and the files defined in each step are as follows.
Step 1

Update database file CARS in deferred update mode. The files defined are:
<table style="width:80%">

<tr>
<td>TAPECARF</td>
<td>
Fixed-length deferred update data set, defined to go to a standard label tape. A LABELDEF command defines the volume serial number.

When <var class="product">Model 204</var> uses a tape, it executes the M204MOUN EXEC to tell an operator to mount the volume label specified in the LABELDEF. The M204UNLD EXEC is executed at the end of tape processing to issue the appropriate z/VM TAPE command function. The version of M204UNLD distributed has a TAPE RUN command. Change this to TAPE REW to run this example.
</td>
</tr>

<tr>
<td>TAPECARV</td>
<td>Variable-length deferred update data set.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN1, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>
</table>

Step 2

Sort the fixed-length deferred update file that has been written in Step 1. This example uses SYNCSORT, which is able to read tape input. A LABELDEF is needed to define the volume serial number.

The SYSIN file to the sort is DEFUPDF SORTCTRL. See the DEFUPD EXEC for the control statement format. 

Step 3

Execute the first Z command to apply the fixed-length deferred updates. The files defined are:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted fixed-length deferred update data set.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>FRV deferred update data set.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN3,containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS </td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk. </td>
</tr>
</table>

Step 4

Sort the variable-length deferred update data set. This example uses SYNCSORT and the sort exits OI15CMS and OI35CMS. These sort exits are provided with the installation. Typically, the sort exits are either placed in a TXTLIB or reside on an accessed disk with a filetype of TEXT.

The SYSIN file to the sort is DEFUPDV SORTCTRL. See the DEFUPD EXEC for the control statement format.:

<table>
<tr>
<td>CCAIN</td>
<td>Sort control statements (same as SYSIN).</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Sort error message file for the variable-length deferred update data set sort. </td>
</tr>
</table>

Step 5

Execute the second Z command to apply the variable-length deferred updates:

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of variable-length deferred update entries.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file. If both a fixed-length deferred update data set and a variable-length deferred update data set are used, the FRV deferred update data set is generated during the processing of the fixed-length deferred update data set (Step 3).</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN5, containing the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step 6

Sort the FRV index file that has been written in Step 3. This example uses SYNCSORT.

The SYSIN file to the sort is FASTLOAD SORTCTRL. This file is provided with the installation. See the DEFUPD EXEC for the control statement format.

Step 7

Apply the FRV deferred updates using the Z command: 

<table style="width:80%">
<tr>
<td>SORT5</td>
<td>Sorted data set of FRV deferred updates.</td>
</tr>

<tr>
<td>TAPE5</td>
<td>Dummy file.</td>
</tr>

<tr>
<td>CCAIN</td>
<td>z/VM disk file, DEFUPD CCAIN7, that contains the commands to open and update the file CARS. A file listing follows the EXEC.</td>
</tr>

<tr>
<td>CARS</td>
<td><var class="product">Model 204</var> database file being updated. The file is defined on a z/OS minidisk.</td>
</tr>
</table>

Step COMMON

Define files common to each step. 

COMMON is executed with Steps 1, 3, 5, and 7. The files defined are:

<table>
<tr>
<td>CCAAUDIT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCAPRINT</td>
<td>Step number is concatenated to the filename to have a separate file for each step.</td>
</tr>

<tr>
<td>CCASTAT</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCATEMP</td>
<td>Previously defined file on a z/OS minidisk.</td>
</tr>

<tr>
<td>CCASNAP</td>
<td>Set to PRINTER to save disk space.</td>
</tr>

<tr>
<td>&STACK</td>
<td>Passes execution parameter SYSOPT 128 in the program stack to FASTLOAD. </td>
</tr>
</table>

===DEFUPD EXEC===

The DEFUPD EXEC input files are:
DEFUPD CCAIN1
SPCORE=50000
OPEN CARS,TAPECARF,TAPECARV
I STORE
CLOSE CARS
EOJ

DEFUPD CCAIN3
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN5
SPCORE=30000
OPEN CARS
Z
EOJ

DEFUPD CCAIN7
SPCORE=27000
OPEN CARS
Z
EOJ

DEFUPDF SORTCTRL
SORT FIELDS=(1,16,CH,A),SIZE=500
INPFIL BLKSIZE=2400
RECORD TYPE=F,LENGTH=(24,24)
OPTION PRINT=ALL
END

DEFUPDV SORTCTRL
SORT FIELDS=(5,75,CH,A)
RECORD TYPE=V,LENGTH=(270,80,270,80)
MODS E15 = (OI15CMS,1500),E35=(OI35CMS,800)
END

FASTLOAD SORTCTRL
SORT FIELDS=(1,16,CH,A)


==Job steps==

The first phase of the deferred update process is performed in one job step. The second phase can involve many separate job steps: two job steps for each deferred update data set generated in the first phase and two job steps for the FRV deferred update data set, if one is generated.

Two basic job steps

The two job steps for processing each deferred update data set are:
<ul>
<li>First job step executes a sort program, such as IBM SORT, to sort the deferred update data set for efficient processing in the next job step.</li>

<li>Second job step executes the BATCH204 load module to process the sorted deferred index information and to update Tables C and D. </li>
</ul>

===Total number of job steps===

The number of job steps in the entire deferred update process depends on the attributes of the fields being updated and the number of deferred index update data sets specified on the OPEN command or IFOPEN call. 

The deferred update process can have three, five, or seven steps. Each type of deferred update process is explained in detail in the following sections. 

[[#Total number of job steps|Determining deferred update process steps]] is a quick reference chart for determining the number of job steps needed, including the first phase job step, for each file placed in deferred update mode. 

<table>
<caption>Determining deferred update process steps</caption>
<tr class="head">
<th>File attributes for all deferred fields in file  </th>
<th>No. of deferred update data sets in OPEN command</th>
<th>No. of sort files required</th>
<th>No. of steps  </th>
</tr>

<tr>
<td>KEY</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and FRV</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY and NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>KEY and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>KEY, FRV, and NUMERIC RANGE</td>
<td>1</td>
<td>2</td>
<td>5</td>
</tr>

<tr>
<td>KEY, FRV, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, FRV, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>2 3</td>
<td>5 7</td>
</tr>

<tr>
<td>KEY, NUMERIC RANGE, and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>NUMERIC RANGE</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>

<tr>
<td>NUMERIC RANGE and ORDERED</td>
<td>1 2</td>
<td>1 2</td>
<td>3 5</td>
</tr>

<tr>
<td>ORDERED</td>
<td>1</td>
<td>1</td>
<td>3</td>
</tr>
</table>

==Seven-step deferred update process==

A seven-step deferred update process is needed when the following conditions occur:
<table style="width:80%">
<tr class="head">
<th>Condition</th>
<th>Description</th>
</tr>

<tr>
<td nowrap>Deferred update mode</td>
<td>File was put in deferred update mode by specifying two deferred update data sets on the OPEN command or IFOPEN call:
<ul>
<li>One fixed-length deferred update data set</li>
<li>One variable-length deferred update data set</li>
</ul>
</td>
</tr>

<tr>
<td>Hashed index fields</td>
<td>Fields with the KEY and/or NUMERIC RANGE attribute are updated and the index updates are deferred to the fixed-length data set. </td>
</tr>

<tr>
<td>Ordered Index fields</td>
<td>ORDERED CHARACTER and/or ORDERED NUMERIC are updated and the index updates are deferred to the variable-length data set.</td>
</tr>

<tr>
<td>Key fields</td>
<td>One or more of the KEY fields updated and deferred also has the FRV attribute. </td>
</tr>
</table>

Seven-step job steps

Follow these steps in the seven-step deferred update process:
<ol>
<li>The first phase step, generate two deferred update data sets: one fixed-length and one variable-length.</li>

<li>Sort the variable-length deferred update data set. (It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.)</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set</li>

<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>

<li>Sort the additional fixed-length deferred update data set.</li>

<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Five-step deferred update process==

Three combinations of field attributes and specified deferred update data sets require five job steps to complete the deferred update process: 

<table style="width:80%">
<tr class="head">
<th>This type...</th>
<th>Does...</th>
</tr>

<tr>
<td>Fixed-length data set with FRV field</td>
<td>Fixed-length deferred update processing for KEY and/or NUMERIC RANGE and FRV fields. </td>
</tr>

<tr>
<td nowrap>Fixed-length and Variable-length data set </td>
<td>Fixed- and variable-length deferred update processing for KEY and/or NUMERIC RANGE and ORDERED fields. </td>
</tr>

<tr>
<td>Variable-length data set and FRV field</td>
<td>Variable-length deferred update processing for KEY, NUMERIC RANGE, and ORDERED fields, and fixed-length deferred update processing for FRV fields.</td>
</tr>
</table>

===When to use Fixed/FRV===

The Fixed/FRV type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields (KEY and/or NUMERIC RANGE) are updated and the index updates are deferred to the fixed-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In this case, either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces updates to the Ordered Index (ORDERED fields) to be updated immediately, and no Ordered Index updates are deferred. 

Fixed/FRV five-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set, which generates an additional fixed-length deferred update data set for FRV fields.</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

===When to use Fixed/Variable===

The Fixed/Variable type of five-step process is needed when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length and one variable-length deferred update data sets on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Fixed/Variable five-step process
<ol>
<li>The first-phase step, generates one fixed-length and one variable-length deferred update data set.</li>

<li>Sort the variable-length deferred update data set. It is not necessary to sort the variable-length data set before the fixed-length data set. Steps 4 and 5 can be switched with steps 2 and 3.</li>

<li>Apply the updates from the sorted variable-length deferred update data set.</li>

<li>Sort the fixed-length deferred update data set.</li>

<li>Apply the updates from the sorted fixed-length deferred update data set. This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.</li>
</ol>

===When to use Variable/FRV===

The Variable/FRV type of five-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE) and/or Ordered Index fields (ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>One or more of the KEY fields updated and deferred also has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set.

Variable/FRV five-step process
<ol>
<li>The first-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set, which generates an additional fixed-length deferred update data set (for FRV fields).</li>
<li>Sort the additional fixed-length deferred update data set.</li>
<li>Apply the updates for the additional sorted fixed-length deferred update data set. </li>
</ol>

==Three-step deferred update process==

The two types of three-step deferred update processes are:
<ul>
<li>Fixed type</li>
<li>Variable type</li>
</ul>

===When to use the Fixed three-step process===

The Fixed type of three-step process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one fixed-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-are updated and the index updates are deferred to the fixed-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

Either no ORDERED fields are updated or the variable-length deferred update data set is intentionally omitted. This omission forces immediate updates to the Ordered Index (ORDERED fields) and no Ordered Index updates are deferred.

Fixed three-step process
<ol>
<li>The first-phase step, generate one fixed-length deferred update data set.</li>
<li>Sort the fixed-length deferred update data set.</li>
<li>Apply the updates from the sorted fixed-length deferred update data set. (This does not generate an additional fixed-length deferred update data set, because there are no FRV fields involved.) </li>
</ol>

===When to use the Variable three-step process===

The Variable type of three-step deferred update process is used when the following conditions occur:
<ul>
<li>File was put in deferred update mode by specifying one variable-length deferred update data set on the OPEN command or IFOPEN call.</li>

<li>Hashed index fields-KEY and/or NUMERIC RANGE-and/or Ordered Index fields-ORDERED CHARACTER and/or ORDERED NUMERIC-are updated and the index updates are deferred to the variable-length data set.</li>

<li>None of the KEY fields updated and deferred has the FRV attribute. </li>
</ul>

In other words, no fixed-length deferred update data set is supplied, so all the deferred updates generated by the first phase are sent to the variable-length data set. 

Variable three-step process

In this case the following steps are necessary in the deferred update process:
<ol>
<li>First-phase step, generate one variable-length deferred update data set.</li>
<li>Sort the variable-length deferred update data set.</li>
<li>Apply the updates from the sorted variable-length deferred update data set. </li>
</ol>

==Merging deferred updates==

It is possible to merge the fixed-length deferred update data sets of many first-phase steps into a single sorted data set. This can be useful when many jobs are used to update one file, and each job produces its own fixed-length deferred update data set. The following restrictions apply to merging deferred update data sets:
<ul>
<li>No KEY or NUMERIC RANGE deferred update records can be deferred to the variable-length deferred update data set.</li>
<li>No variable-length deferred update data sets can be merged. </li>
</ul>

The merged fixed-length deferred update sort output is used as input for a single index step. A single index step can handle a maximum of 2,147,483,648 (or 231) deferred update records. 

The variable-length deferred update data set cannot be merged. If the fixed-length deferred update data sets produced in the same first-phase steps as the variable-length data sets are merged, the variable-length deferred update data sets must still be processed separately and in chronological order.

Although merging several deferred update data sets can produce a cost reduction in the next step, other considerations, such as error recovery, can make merging undesirable. 

==Overriding deferred updates==

Consider the following type of update situation: new records are to be added to an automobile file in which each record has a unique SERIAL NUMBER field, which is KEY. Before a record is added, the user issues a FIND statement to see if any other record already exists with the same value of SERIAL NUMBER. If one is found, the new record is not added.

If updates to the index are deferred, the FIND fails to locate duplicate records that already have been added in the same main step. In order to avoid this situation, define the field SERIAL NUMBER with the NON-DEFERRABLE attribute.

===Deferring updates in single-user runs===

In single-user runs, however, there is usually no reason not to defer updates. Consequently, in single-user runs, if a file is in deferred update mode, the NON-DEFERRABLE attribute is ignored by <var class="product">Model 204</var>. If you must prevent updates to a field from being deferred in a single user environment, use the following technique to simulate a multiuser environment and thereby force the NON-DEFERRABLE fields to be updated immediately: 
<ul>
<li>On User 0's parameter line in the main job step, set NUSERS = 2. </li>

<li>Follow User 0's parameter line with a second parameter line that contains IODEV=3, INPUT=T03U001I, and OUTPUT=T03U001O. </li>

<li>Include these three statements in the JCL for the main step:
//T03U001I DD *
/*
//T03U001O DD SYSOUT=A
</li>
</ul>

For z/VSE, specify the IODEV=3 input and output file names using z/VSE system logical names that are assigned to "IGN" in the JCL.

===Handling a deferred update override===

If you override the deferred update feature, you must manually turn off the [[File Load utility: FLOD and FILELOAD commands#Internal file load optimization feature|file load optimization feature]]. To turn this feature off, specify a read-and-load-a-field statement with the delete mode bit, and then include a branch before the statement so that it never executes. 

For example:
DEFINE FIELD DUMMY Define a dummy field before
. the FILELOAD statement.
.
.
=5 Branch to 5
DUMMY=1,0.X'4000' Turn on delete mode bit
#5 Always skip DUMMY statement.
.
.
.


===Deferred updates for NON-DEFERRABLE fields===

There are times in <var class="product">Model 204</var> in which updates are deferred for NON-DEFERRABLE fields. Some NON-DEFERRABLE fields are deferred if the file is opened in deferred update mode and NUSERS=1 (that is, the file is opened in single user mode).

The following table describes the conditions under which the updates are deferred for NON-DEFERRABLE fields. 

<table>
<caption>Deferring NON-DEFERRABLE fields</caption>
<tr class="head">
<th>Condition</th>
<th>Fixed-length data set only</th>
<th>Variable-length* data set only</th>
<th>Fixed- and variable-length* data sets</th>
</tr>

<tr>
<td>UNIQUE through FLOD</td>
<td>N/A</td>
<td>KEY and ORD deferred</td>
<td>KEY deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>UNIQUE without FLOD</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
<td>No updates deferred</td>
</tr>

<tr>
<td>NON-UNIQUE through FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td>NON-UNIQUE without FLOD</td>
<td>KEY and NR deferred</td>
<td>KEY, NR, and ORD deferred</td>
<td>KEY, NR deferred to Fixed 
ORD deferred to Variable</td>
</tr>

<tr>
<td colspan="4">*A variable-length data set is required for ORDERED fields loaded through FLOD.</td>
</tr>
</table>
Note: If new fieldname=value pairs are created (for example COLOR=BLUE, where BLUE is a new property entry) you can generate and defer FRV index updates during the Z-step of a KEY index.

===Deferred updates and Reuse Record Number files===

Do not use deferred update mode with Reuse Record Number (RRN) files except where you are performing simple record adds, such as reorganizing files. Using deferred update mode with RRN files might cause you to lose updates without any warning. For more information, see [[File design#RRN files and deferred update mode|RRN files and deferred update mode]].

[[Category:Model 204 files]]

Field design

2015-07-30T23:22:31Z

Tbullock: Fix the message to the way it really is in 7.5

==Overview==

The field structures in <var class="product">Model 204</var> are at the heart of providing applications which perform the functions that you require in the most efficient manner possible.

This page discusses exactly how the data structures should be defined.

==Designing records, field groups, and fields==

When setting up a <var class="product">Model 204</var> file, you must first decide what fields the records will contain. A record in a personnel file, for instance, might contain a social security number field, a last name field, a spouse's name field, and so on. 

===Variable record formats===

The record in <var class="product">Model 204</var> is a very loose concept. Physically, it is simply a collection of fields (data items).

Any field in the [[#Table A (File architecture) Internal File Dictionary|Table A dictionary]] can appear in any record in the file. It is quite possible that you create a file with many different logical record types with only a few (or even none) appearing in all of the records.

Thus, each record is not required to have a value for every field; so that record lengths are variable, and it can be argued that the entire concept of a record "format" does not apply to Model 204 files. If an employee's address is unknown or doesn't exist in a particular logical record, for example, the address field will be left out of the record altogether. The exception to this is [[#Preallocated fields (OCCURS attribute)|preallocated fields]]. If they are are defined for a file, space is reserved in each record for all such fields, even if they would never exist for that logical record. 

===Multiply occurring fields===

Most types of fields can be multiply occurring, that is, have more than one value per record. For example, the <code>CHILD</code> field can appear no times, once, or several times in one record. 

==Field descriptions and attributes==

When you describe a field in a <var class="product">Model 204</var> file with the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> or <var>[[REDEFINE command|REDEFINE FIELD]]</var> command, you specify a field description that consists of the field name followed by a list of field attributes. These attributes determine how a field can be accessed and how it is stored internally. This section describes the attributes supported for <var class="product">Model 204</var> fields. 

Within a record, there is usually no restriction on the number of different fields that can have the same attribute (the exception being the key fields for Sorted and Hash Key files). For example, several fields within the same record can have ORD CHAR indices built for them.

Attribute assignments

The attribute assignments apply whether the field was defined separately or as part of a [[Field group (File architecture)|field group]].

If you do not assign a particular attribute to a field, the default attribute is assigned. For example, if you do not assign the <var>KEY</var> attribute to a field definition, the field is assigned <var>NON-KEY</var>.

If a required attribute is not assigned a value, the default value is used. For example, if you define a CONCATENATION-OF field, which requires the SEPARATOR attribute, and you do not enter the SEPARATOR attribute, the default value of X'00' is used as the SEPARATOR value.

Multiply occurring fields

For most field attributes there is almost no restriction on the number of times a particular field can occur within a record. This makes file/record design very flexible. If you have a record which has child details as repeating fields or groups, for example, any number can be supported. 

Singly occurring fields

There are a few attributes which require a field to have no more than one occurrence per record:
<ul>
<li>NUMERIC RANGE
<li>Sort key fields
<li>Hash key fields
</ul>

Others require a field to have no more than one occurrence per record or field group (depending on the context in which they are defined):
<ul>
<li>AT-MOST-ONE
<li>EXACTLY-ONE
</ul>

==Indexing fields==
Model 204 files can become quite large, and so it is almost always preferable to directly access the record or records which have particular characteristics. As part of your design process, you should have identified which field(s) are likely to be used for direct retrieval of sets of records.

For example, if you have a personnel file, you are likely to have a unique identifier for each employee, and it is also likely that you will often want to process only the record or records with that ID.

Where retrievals are attempted against non indexed fields, a search of Table B must be done, and the danger of request cancellation because [[MBSCAN parameter|MBSCAN]] is exceeded exists.

Model 204 supports a few different ways to implement these direct searches, and the recommended default choice for indexing is the ORDERED attribute.

===ORDERED and NON-ORDERED attributes===

Fields used in retrieval specifications should normally be defined as ORDERED (unless one of the other indexing methods, described below) is chosen. NON-ORDERED, the default, means that all retrieval requests need to scan the records directly in Table B to find the selected records.

For the architectural approach to the implementation of the ordered index, refer to [[Table D (File architecture)#Understanding the Ordered Index|understanding the Ordered Index]].

====Choosing an order type====

An ORDERED field can have an index with either CHARACTER or NUMERIC ordering. This is called its order type. The field's order type and updating characteristics are declared with the DEFINE command. You can specify only one order type for a field. ORDERED NUMERIC fields contain numeric values stored as standardized floating-point numbers in one section of the index and non-numeric values in EBCDIC order in another section. 

=====ORDERED CHARACTER fields=====

ORDERED CHARACTER fields use the standard EBCDIC collating sequence. If a field is ORDERED CHARACTER, all values of the field are stored in the Ordered Index in EBCDIC collating sequence order.

=====ORDERED NUMERIC fields=====

A string field value is considered NUMERIC if it consists of digits, with one optional decimal point, and an optional plus or minus sign at the beginning of the string. The value of the number cannot be greater than 10 to the power 75 or less than 10 to the power -75. 

If an ORDERED NUMERIC field is also FLOAT, exponential format is allowed. Values for BINARY, FLOAT (8), and FLOAT (16) fields are rounded to 15 significant digits. Values for FLOAT (4) fields are rounded to 6 significant digits. 

An invalid value is stored as an unconverted string. 

In ORDERED NUMERIC fields, leading zeros are ignored. For example, 001 and 1 are considered equivalent and are maintained in the ORDERED NUMERIC portion of the B-Tree as the same value. For fields that require a meaningful leading zero (such as zip code), use ORDERED CHARACTER.

Values of an ORDERED NUMERIC field that do not satisfy the definition of NUMERIC are stored in a separate section of the Ordered Index and processed in EBCDIC order. During FOR EACH VALUE and FOR EACH RECORD IN ORDER BY FIELD processing of an ORDERED NUMERIC field, these values are processed after the valid NUMERIC values unless you restrict the range of values. 

=====Default order types=====

If a field is defined as ORDERED without specifying which type of ordering to create, a default order type is used. The default depends on whether the field is STRING, BINARY, or FLOAT:
<table>
<tr class="head">
<th>For...</th><th>The default order type is...</th>
</tr>

<tr>
<td>STRING</td><td>ORDERED CHARACTER</td>
</tr>

<tr>
<td>BINARY or FLOAT</td><td>ORDERED NUMERIC </td>
</tr>
</table>

====ORDERED field definition====

The ORDERED attribute has options that allow you to determine the type of ordering the Ordered Index is to have, as well as some of the characteristics of the Ordered Index tree as it expands or is rebuilt. These options are described in the discussions of order type and Ordered Index tree structure that follow.

=====Defining ORDERED field attributes=====

The [[DEFINE command]] is used to specify a field's attributes. The format of the DEFINE command with the ORDERED attribute options is:

=====Syntax=====
DEFINE FIELD fieldname WITH ORDERED
[CHARACTER | NUMERIC][SPLITPCT s] [IMMED i]
[LRESERVE <var class="term">r</var>] [NRESERVE n]

<blockquote class="note">Note:

The default designation for a field is NON-ORDERED. Ordered Index tree parameters do not apply for a NON-ORDERED field. 

<var>CHARACTER</var> and <var>NUMERIC</var> order types are described above.

<var>SPLITPCT</var>, <var>IMMED</var>, <var>LRESERVE</var>, and <var>NRESERVE</var> parameters are described in [[Table D (File architecture)#Ordered Index spacing parameters|Ordered Index spacing parameters]]. 
</blockquote>

=====Redefining ORDERED fields=====

To change the type of ordering of an ORDERED field, use the [[REDEFINE command]] followed by the new ordering type, thereby deleting the old type. To change the spacing characteristics, specify the current parameter (LRESERVE, NRESERVE, SPLITPCT, or IMMED) with a new value. This takes effect only for fields added after the change.

====Choosing between ORDERED and NUMERIC RANGE====

The ORDERED attribute has several advantages over the NUMERIC RANGE attribute, and as such should be the normal choice. Specifically: 
<ul>
<li>Ordered Index allows for multiple occurrences of the same numeric field in a record. The NUMERIC RANGE attribute issues an error message whenever an attempt is made to store more than one occurrence of the same NUMERIC RANGE field in the same record.</li>

<li>Cost of updating an ORDERED field is lower than that of a NUMERIC RANGE field. The NUMERIC RANGE field requires multiple attributes to be maintained to describe the characteristic of a number. The cost of an update to the Ordered Index is always proportional to the depth of the tree.</li>

<li>In most cases, especially with large numbers, the Ordered Index uses less space to maintain the index information.</li>

<li>Ordered Index allows for more accurate range requests, with numbers representable by IBM double-word floating-point numbers. </li>
</ul>

=====Range retrievals=====

Although range retrievals are usually faster for ORDERED fields than for NUMERIC RANGE fields, the size of the range interval and the density of the distribution of values over that range are the principal determining factors.

In the past, NUMERIC RANGE retrievals have been faster for very large ranges with densely distributed data values. 

=====CHUNK attribute=====
However, as of Model 204 version 7.5, you can improve the efficiency of data range retrieval on ORDERED NUMERIC fields by defining the fields with the <var>[[DEFINE FIELD command#CHUNK attribute|CHUNK]]</var> attribute.

The CHUNK attribute defines a subrange ("OI chunk") of the Ordered Index data range, so the desired data can be found with fewer scans of the Ordered Index entries.

CHUNK fields are AUTOMATIC fields and therefore require that FILEORG X'100' be set for the file.

The CHUNK attribute is followed by a number, defining the size of the OI chunk, and then FOR <var class="term">chunkTargetFieldName</var>, where <var class="term">chunkTargetFieldName</var> is the existing ORDERED NUMERIC field from which you want to retrieve data in OI chunks.

So, to illustrate:
DEFINE FIELD YYYYMMDD WITH ORDERED NUMERIC
DEFINE FIELD YYYYMM WITH ORDERED NUMERIC INVISIBLE CHUNK 100 FOR YYYYMMDD


A CHUNK field is automatically maintained based on updates to the target (FOR) field (here, YYYYMMDD). The stored value is the value of the target field rounded down to the CHUNK size. So, for example, if you stored a value of 20121225 into YYYYMMDD, the underlying code would automatically store the value 20121200 into YYYYMM. Similarly, if you stored 20121203 into YYYYMMDD, a 20121200 value would also be stored into YYYYMM.


When doing a range find, Model 204 decomposes the find into range finds based on the CHUNK field and the target field.
So, for example, a find for values between 20121211 and 20130205 would be decomposed into a find for:

<ul>
<li>YYYYMMDD between 20121211 and 20121299 (ignoring for the moment issues with non-integer values and demonstrating that CHUNK doesn't really know or care if the field is a date)</li>

<li>OR YYYYMM between 20130100 and 20130100 (or more precisely, exactly equal to 20130100)</li>

<li>OR YYYYMMDD between 20130200 and 20130205</li>
</ul>

This reduces the number of scanned ordered index entries by a factor of 2.
Results would often be much better than that. For example, it probably would not be atypical for a date range to land on month boundaries, resulting in improvements closer to a factor of 30. And, as the range got bigger and bigger, more and more of the range processing would occur on the CHUNK field, with additional improvement in processing.


=====Multiple CHUNK fields=====

To get even better performance, you could define multiple CHUNK fields for a target field:

DEFINE FIELD YYYYMMDD WITH ORDERED NUMERIC
DEFINE FIELD YYYYMMD WITH INVISIBLE ORDERED NUMERIC CHUNK 10 FOR YYYYMMDD
DEFINE FIELD YYYYMM WITH INVISIBLE ORDERED NUMERIC CHUNK 100 FOR YYYYMMDD
DEFINE FIELD YYYY WITH INVISIBLE ORDERED NUMERIC CHUNK 10000 FOR YYYYMMDD


The OI chunk size for a CHUNK field must be a greater-than-1 integral multiple of all smaller OI chunk sizes for the same target field. For example, specifying "7" as the first CHUNK size in the above example would be invalid because 100 is not an integral multiple of 7.

Note that you could reference the CHUNK fields directly in non-updating statements, as shown in this example:

fd to %recset
yyyy eq %year
end find


In any case, the number and size of the CHUNK fields allows you to trade off the overhead of doing updates against the efficiency of doing range finds. 

====Choosing between ORDERED and FRV====

The ORDERED attribute is usually a better alternative to the FRV attribute. Although FRV fields with small numbers of values might perform faster in value loop processing, they lose this advantage if the found values are required to be in order, and as the number of values increase. FRV ordered retrievals require additional sorting. For retrievals in ascending or descending order, ORDERED fields are more efficient. For (presumably rare) right-adjusted character strings in order, ORDERED fields require additional sorting.

=====Compatibility of ORDERED with other field attributes=====

Use the following guidelines when specifying the ORDERED attribute:
<ul>
<li>A field cannot be both ORDERED and FRV.</li>
<li>A field cannot be both ORDERED NUMERIC and NUMERIC RANGE.</li>
<li>A field can be both KEY and ORDERED (but serves little or no purpose).</li>
<li>A field can be both INVISIBLE and ORDERED.</li>
<li>A field can be both DEFERRABLE and ORDERED. If the field is DEFERRABLE, the index updates can be written out to a (see [[#DEFERRABLE and NON-DEFERRABLE attributes|DEFERRABLE and NON-DEFERRABLE attributes]] for details). </li>
<li>UNIQUE field must be ORDERED. </li>
<li>Hash and sort key fields and record security fields can be ORDERED.</li>
<li>Fields which are defined as KEY can be converted to ORD with no code changes required (as direct retrievals will work with either type of ORD field).</li>
</ul>

For an architectural view of the ordered index, see [[#Table D (File architecture) Ordered Index|the Ordered Index]].

===KEY and NON-KEY attributes===

The KEY and NON-KEY attributes govern whether to create a hash index for a field or not. If KEY is specified, an index is created for the field. Retrieval commands will access the index for that field. If NON-KEY is specified, every record in the table is examined. The NON-KEY attribute is a default field description. This section provides information about space and performance for each of these attributes.

=====KEY attribute=====

When storing fields that have the KEY attribute, <var class="product">Model 204</var> makes special entries in the hash index. During retrieval, <var class="product">Model 204</var> goes directly to the appropriate index entry to find which records satisfy the selection criteria, without searching through other records in the file. This makes retrieval based on KEY fields extremely fast. 

However, these index entries must be updated, when User Language statements or Host Language Interface functions add, change, or delete fields. Processing might take slightly longer for KEY fields than for NON-KEY fields. In addition, the space occupied by the index entries can be considerable, especially in large files and in fields that take on many values. 

=====NON-KEY attribute=====

No index entries are maintained in Tables C and D for NON-KEY fields. When a retrieval is performed based on the value of NON-KEY fields, the data in Table B must be searched directly. The direct search can have a significantly adverse effect on performance, if a large number of records must be searched. 

However, the cost of the direct search can be greatly reduced in some cases where both KEY and NON-KEY fields are specified in the retrieval conditions. <var class="product">Model 204</var> reduces the number of records to be searched directly by performing the indexed selection first. Records that are definitely eliminated, based on the KEY conditions, are not searched directly. 

=====Choosing between KEY and NON-KEY=====

Keep the following guidelines in mind when deciding to designate a field as KEY or NON-KEY:
<ul>
<li>If space is not an overriding consideration, designate fields that are used frequently for retrievals of equality as KEY.</li>

<li>If a field is updated frequently and only occasionally used for retrieval, define it as NON-KEY.</li>

<li>If a field is used frequently for retrievals and updated frequently, the choice is less obvious. If you reserve sufficient space in Tables C and D for adding inversion entries, the field initially can be defined as NON-KEY and changed later with the <var>REDEFINE</var> command. </li>
</ul>

===FOR EACH VALUE (FRV) and NON-FRV attributes===

The FRV attribute is useful when creating fields used in value loop processing. If the FRV attribute is not specified when a field is defined, the NON-FRV attribute is assumed. If this attribute is set, the field is usually assigned the KEY attribute as well. 

====Table space for FRV fields====

Every value of an FRV field is automatically encoded in Table A, whether or not the value is stored in Table B (that is, INVISIBLE). In addition to more Table A space, FRV fields require slightly more Table C and Table D space than ordinary key fields. Because of these additional space requirements, the FRV attribute is most frequently defined for fields in which the number of different values does not exceed approximately 200.

====Using the FRV attribute====

The FRV attribute behaves in a special way when combined with the BINARY attribute. This is discussed in [[#BINARY attribute|BINARY attribute]].

Fields cannot be defined with the FRV attribute in [[Field attributes#File model feature|First-Normal Form (1NF)]] files. 

====FRV attribute, FRV User Language statement====

=====Value loops=====

User Language provides a special construction called a value loop that executes a set of statements once for each different value of an indicated field. The loop is initiated by the FOR EACH VALUE statement; the field must have the FRV or ORDERED attribute. The FOR EACH VALUE statement has Host Language equivalents in IFFDV and IFGETV. A value loop is illustrated in the following example:

Example
EACH.STATE:
FOR EACH VALUE OF STATE
GET.RECS:
FIND ALL RECORDS FOR WHICH
STATE = VALUE IN EACH.STATE
END FIND
TOT.RECS:
COUNT RECORDS IN GET.RECS
PRINT.CT:
PRINT VALUE IN EACH.STATE -
WITH COUNT IN TOT.RECS AT COLUMN 20
END FOR


On the first pass through the loop, a value of STATE, such as DELAWARE, is selected. The last statement prints DELAWARE and the number of records with the field-name-equals-value pair: STATE = DELAWARE. On the next pass, another value is chosen, such as IOWA, and so on until all values of the STATE field have been processed exactly once.

=====Using the IN ORDER option=====

The IN ORDER option of the FOR EACH VALUE statement specifies that the values of an FRV KEY field be presented in an ordered sequence-ascending, descending, numerical, right adjusted. This option improves performance by avoiding Online sorts of a large number of records, because only the values are sorted instead of a large found set of records. 

=====Value loop processing for ORDERED fields=====

You can also use value loop processing on fields with the ORDERED attribute. When the FOR EACH VALUE statement with the IN ORDER option is used for NON-FRV, ORDERED fields, ORDERED retrievals can be significantly faster than FRV ordered retrievals. See [[#ORDERED and NON-ORDERED attributes|ORDERED and NON-ORDERED attributes]] for a description of the ORDERED attribute. 

Value loop processing can be made more flexible and efficient by using [[Is_Like_pattern_matching#Pattern matching|pattern matching]].

===NUMERIC RANGE and NON-RANGE attributes===

Prior to the introduction of ORDered NUMeric fields, Model 204 permitted range retrieval (a field value numerically equal to, less than, greater than, or between certain values) with the NUMERIC RANGE attribute. This attribute indexes the component parts of a numeric value and then joins them, to provide rapid numeric range retrievals without a direct search of the records.

If the NUMERIC RANGE attribute is not specified when a field is defined, the NON-RANGE attribute is assumed. 

It is recommended that, for any new fields being defined,the ORDERED NUMERIC attribute is used in preference to NUMERIC RANGE.

The NUMERIC RANGE attribute cannot be set where the product ([[ASTRPPG parameter|ASTRPPG]] * [[ATRPG parameter|ATRPG]]) is greater than 4000 (available in <var>[[FILEORG parameter|FILEORG]]</var> X'100' files).

====NUMERIC RANGE retrieval specifications====

The following retrieval specifications, with their symbolic operator equivalents in parentheses, can be used:
fieldname IS value
fieldname IS EQ (=) value
fieldname IS LESS THAN (LT or <) value
fieldname IS GREATER THAN (GT or >) value
fieldname IS BETWEEN (GT or >) value AND (LT or <) value
fieldname IS GREATER THAN (GT or >) value AND LESS THAN (LT or <) value
fieldname IS LESS THAN (LT or <) value AND GREATER THAN (GT or >) value


====Examples====

The following examples show numeric retrieval specifications:
ALL:
FIND ALL RECORDS FOR WHICH AMOUNT IS 53.00
DATE IS BETWEEN 050500 AND 050532
END FIND


These specifications retrieve records for which AMOUNT has a value of 53.00 (or 53 or 053, and so on) and DATE has a value in May 2005.

====NUMERIC RANGE retrieval fields====

The values of NUMERIC RANGE retrieval fields can be either positive or negative numbers that have as many as ten digits on either side of the decimal point (20 digits maximum). When such fields are stored, <var class="product">Model 204</var> makes many entries in Tables C and D as well as some special entries in the field name (attribute) section of [[Table A (File architecture)|Table A]]. These entries are quite complex, and NUMERIC RANGE retrieval fields require both more storage space and more time to store and update than do KEY fields. 

In deciding whether to define a field as NUMERIC RANGE or NON-RANGE (and NON-ORDERED), use the same choice criteria described in [[#KEY and NON-KEY attributes|KEY and NON-KEY attributes]], keeping in mind the additional overhead caused by the extra index entries for RANGE fields.

====Interpreting nonnumeric values====

If a NUMERIC RANGE field is stored with a value that <var class="product">Model 204</var> cannot interpret as a number, the system stores a special index entry for the record. The field name of this special entry consists of the NUMERIC RANGE retrieval field name with ++ appended. The entry has a value of NON NUMERICAL. Thus, the following User Language retrieval retrieves all records with nonnumerical values of AGE:
ALL:
FIND ALL RECORDS FOR WHICH
AGE++ = NON NUMERICAL
END FIND


This can be useful in locating bad input data.

====Compatibility with other attributes====

You can specify as many NUMERIC RANGE retrieval fields in each record as you need. However, a particular NUMERIC RANGE retrieval field cannot be multiply occurring within any one record.

You cannot specify the NUMERIC RANGE attribute in the following circumstances:
<ul>
<li>With any field defined as FLOAT</li>
<li>For any field in a 1NF file</li>
</ul>

For a table showing invalid attribute combinations, see the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command. If you are defining field attributes with FILEMGMT, you will not be allowed to specify conflicting attributes.

== Data typing ==

The following attributes are described individually in the next sections. They represent the way the field is physically stored. Only one of these can be assigned to any field.
<ul>
<li>STRING</li>
<li>BINARY</li>
<li>BLOB, CLOB, MINLOBE</li>
<li>FLOAT</li>
<li>DATETIME</li>
<li>UTF-8 or UTF-16</li>
<li>VISIBLE, INVISIBLE</li>
</ul>

===STRING attribute===

STRING is the default attribute for all fields. If your data is character or alphanumeric, such as names and addresses, specify a data type of STRING. STRING fields are also useful if you plan to store mixed data types in an image. 

The length of a STRING field is limited to 255 bytes, because the first byte of a STRING data field is a count byte-that is, a byte that contains the length of the rest of the string. 

===BINARY attribute===

Fields whose values are numeric integers can alternatively be compressed and stored as 4-byte binary numbers with the BINARY attribute. Specifying BINARY saves Table B space if the average value of the field is from 4-9 digits long.
Acceptable BINARY values

To be compressed successfully, the value must be1-9 digits long and can contain a minus sign. It cannot contain a plus sign, a decimal point, or leading zeros. If the value cannot be compressed, <var class="product">Model 204</var> refers to the CODED/NON-CODED field attribute (which the BINARY attribute usually overrides) to decide how to store the value. 
BINARY and FRV fields

The BINARY attribute overrides the FRV attribute, except for values that cannot be compressed. If the field cannot be compressed, it will be stored in Table A in either the FEW-VALUED or MANY-VALUED pages depending on the field definition. For instance, AGE has been defined with the BINARY and FRV attributes and takes on the values:
23, 04, -34578, 935., 20,
+8754, and TWO


The statement FOR EACH VALUE OF AGE retrieves only the values:
04, 935., +8754 and TWO


If BINARY is not specified when a field is defined, the STRING attribute is assumed.
BINARY fields and NUMERIC VALIDATION files

If a BINARY field is defined in a NUMERIC VALIDATION file model file ([[FILEMODL parameter|FILEMODL]] = X'01'), <var class="product">Model 204</var> provides numeric data type validation. If you try to store non-numeric or other non-conforming (that is, non-compressible) data in a BINARY field in a NUMERIC VALIDATION file, <var class="product">Model 204</var> cancels the request with the following message:
M204.2123: VALUE SPECIFIED VIOLATES BINARY DATA TYPE VALIDATION IN RECORD <var class="term">recno</var>, FIELD IGNORED: <var class="term">fieldname</var> = <var class="term">value</var>


<div id="BLOB attribute"></div>
<div id="CLOB attribute"></div>
<div id="MINLOBE attribute"></div>
===BLOB, CLOB, and MINLOBE attributes===


Note: The MINLOBE attribute is available as of Model 204 version 7.5.

The BLOB and CLOB attributes describe Large Object data that can be used to store long strings in the database, for example, long XML strings. This means that <var class="product">Model 204</var> User Language threads can exchange Large Object data with a partner process by way of the Universal Buffer and/or the MQ/204 Interface. 
<ul>
<li>With the Universal Buffer, Large Object data can be sent and received using User Language READ IMAGE and WRITE IMAGE statements, or $SOCKET READ and WRITE calls.</li>

<li>With the MQ/204 Interface, Large Object data can be sent and received by MQPUT and MQGET statements, stored and retrieved from the database with User Language STORE, ADD, and assignment statements using the BUFFER reserved area name.</li>
</ul>

Note: Files created in V6R1.0 and later are not compatible with earlier versions of <var class="product">Model 204</var>, because of Large Object support and the concomitant changes to the FPL page.

====Introducing Large Object field types====

The Large Object field types includes the following Character Large Object (CLOB) and Binary Large Object (BLOB) attributes. 
<ul>
<li>CLOBs are character strings. </li>
<li>BLOBs are binary strings. No translation is performed when the object is sent or received.</li>
</ul>

Note: Because Large Object fields require that Table E be present in a file, you cannot simply add a Large Object field to an existing file created in a pre-6.1 version of Model 204. You would need to rebuild the existing file by downloading the data and procedures; recreate the file to establish Table E; define the Large Object fields to incorporate; and load the data.

====Limitations of Large Object support====
<ul>
<li>Currently there is a limit of 2,147,483,647 bytes (or two gigabytes) of data per Large Object.</li>

<li>For CLOBs the translation of ASCII to EBCDIC and back is handled by the design of your application.</li>

<li>For BLOBs no translation is performed.</li>

<li>The User Language INSERT statement is not supported.</li>
</ul>

====Handling Large Object data====

The BLOB and CLOB attributes are supported as follows:
<ul>
<li>You can create, open, and recover a file with a BLOB or CLOB attribute. The Large Object field can be multiply occurring. </li>

<li>The DELETE fieldname statement supports the Large Object data. This statement frees the Table B and Table E data.</li>

<li>You can store and add a Large Object data to the file you have created from the Universal Buffer, BUFFER. Using an assignment statement you can transfer Large Object data from a field into the Universal Buffer.</li>

<li>You can set the number of Table E pages during file creation with PARAMETER ESIZE= n.</li>

<li>You can view the EHIGHPG parameter to determine the highest number of Table E pages in use.</li>

<li>You can modify the size of Table E with an INCREASE or DECREASE command.</li>

<li>The DELETE FIELD fieldname command supports the Large Object field type, so you can delete a Large Object field name. However, the space in Table B and Table E is not automatically available for reuse. </li>

<li>[[$LOBLEN|$LOBLEN]](lob-field-name) function is available for your use.</li>
<li>Dictionary/204 and the Cross-Reference facility support Large Object field types.</li>

<li>NULL Large Object data is supported.</li>

<li>Transaction back out is supported for Large Object field types.</li>

<li>Field-level security is supported.</li>
</ul>

====BLOB and CLOB compatibility with other attributes====

See the table in <var>[[DEFINE_FIELD_command|DEFINE FIELD]]</var> for a list of attributes that are not allowed with BLOB or CLOB. Use of conflicting attributes produces the following message:
M204.0411: CONFLICTING ATTRIBUTES: ([BLOB | CLOB]) <var class="term">attribute2</var>


<div id="Using the MINLOBE attribute"></div>
====Using the MINLOBE (MLBE) attribute====

You can use the MINLOBE attribute only with a BINARY LARGE OBJECT (BLOB) or a CHARACTER LARGE OBJECT (CLOB) field in a file with FILEORG X'100'. The MINLOBE attribute cannot be paired with the OCCURS attribute. You can redefine the MINLOBE attribute value.

Syntax
MINLOBE nnn


The default and smallest value for MINLOBE is 0, which means that all values of the field are stored in Table E. The maximum value of MINLOBE is 200.

If a field has the MINLOBE attribute greater than 0:
<ul>
<li>And the value of the field is not longer than MINLOBE, then the value is stored in Table B or Table X, instead of Table E.</li>

<li>The User Language CHANGE statement is not allowed and the following error is displayed:
M204.2869 Change refused: MINLOBE > 0 for File filename field fieldname
Any CHARACTER LARGE OBJECT or BINARY LARGE OBJECT field which does not use the CHANGE statement benefits from setting MINLOBE 200.
</li>

<li>The RESERVE clause is ignored on the User Language ADD statement.</li>
</ul>

====Storing and updating LOBs====

All large object data (LOBs) in a FILEORG X'100' file are chained. There are four bytes per Table E page overhead for chained LOBs. The pages used by a chained LOB are not contiguous.

Handling LOBs in FILEORG X'100' files also has the following effects:
<ul>
<li>The RESERVE clause is ignored in a LOB field ADD statement processing, as well as the STORE RECORD statement processing of fieldname=value pairs.

Consequently, the CHANGE statement does not fail because of insufficient reserved space. If the CHANGE statement requires that a LOB field be extended, it is.
</li>

<li>The value of the [[EHIGHPG parameter|EHIGHPG]] parameter is always one less than the high water mark of the number of pages used to hold LOBs. (Unless none were ever added, in which case it is zero, not -1).</li>

<li>The value of the [[EPGSUSED parameter|EPGSUSED]] parameter is always the number of pages currently being used to hold LOBs.</li>

<li>The [[COMPACTE command|COMPACTE]] command does not process FILEORG X'100' files, just as it does not process a file created in V6R1 or earlier. Thus, issuing a COMPACTE command for a FILEORG X'100' file produces an error message.</li>

<li>The [[TABLEE command|TABLEE]] command effectively does a [[VIEW command|VIEW]] ESIZE EHIGHPG EPGSUSED for a FILEORG X'100' file. Consequently there are no TABLEE overhead pages in a FILEORG X'100' file.</li>
</ul>

===FLOAT attribute===

Any field whose values are always, or almost always, numeric might be more efficiently stored in a floating-point representation than in character form. Using FLOAT can also reduce the time spent in data type conversions for fields used frequently in User Language or Host Language Interface computations. 

Very large or very small numbers, or numbers with many significant digits, occupy considerably less space in floating-point form. 

Floating-point fields are fully supported by User Language, the Host Language Interface, and the File Load utility. For more information about storing values in floating-point fields, see the SOUL [[Floating point conversion, rounding, and precision rules]].

Note
If FLOAT is not specified when a field is defined, the STRING attribute is assumed.

Defining floating point fields

Field values are stored in floating-point by specifying the FLOAT attribute in the DEFINE FIELD command and supplying a LENGTH of 4, 8, or 16. The length supplied determines the precision of the floating-point field being defined. For example, to define a long precision field, specify:
Syntax
DEFINE FIELD <var class="term">fieldname</var> WITH FLOAT LEN 8


You can define three types of floating point fields through the FLOAT and LENGTH attributes.:
<table>
<tr class="head">
<th>
Type of floating-point field</th>
<th>

Occupies...</th>
<th>
Holds a maximum of...</th>
<th>Model 204 maintains a maximum precision of...</th>
</tr>

<tr>
<td>Short precision</td>
<td>4 bytes</td>
<td> 6 significant digits</td>
<td> </td>
</tr>

<tr>
<td>Long precision</td>
<td>8 bytes</td>
<td>15 significant digits </td>
<td>15 significant digits</td>
</tr>

<tr>
<td>Extended precision</td>
<td>16 bytes </td>
<td>31 significant digits</td>
<td>15 significant digits </td>
</tr>
</table>
Acceptable values

The floating-point data type uses IBM hardware's floating-point representation.

A value of negative zero (X'800...0') cannot be stored in a preallocated FLOAT field. 

FLOAT with NUMERIC VALIDATION files

If you define a FLOAT field in a NUMERIC VALIDATION file model file ([[FILEMODL parameter|FILEMODL]]=X'01'), <var class="product">Model 204</var> provides numeric data type validation. Trying to store non-conforming data in a FLOAT field in a NUMERIC VALIDATION file causes <var class="product">Model 204</var> to cancel the request with the following message:
M204.2124: VALUE SPECIFIED VIOLATES FLOAT DATA TYPE VALIDATION IN RECORD recno, FIELD IGNORED: fieldname = value


Compatibility with other attributes

STRING, BINARY, NUMERIC RANGE, and INVISIBLE cannot be specified for a FLOAT field. 

===Storing invalid numeric data: FLOAT or ORDERED NUMERIC===

The valid range of floating point numbers is:
1E-74 through 7.2370E+75


Model 204 enforces storage rules for floating point numbers outside the valid range:
<ul>
<li>If 7.2371E75 is stored in a FLOAT field, the value is treated as an invalid floating point number and is stored as a data string '7.2371E75'.</li>

<li>1E-75 is treated as an invalid floating point number and stored as a data string '1E-75'.</li>
</ul>

If an invalid value is stored for a field with the ORDERED NUMERIC attributes, the value stored in the Ordered Index is the data string. That data string is stored on the Invalid Numeric Data portion of the Ordered Index. This changes the output order of these values when the ordering is done against the Ordered Index, for example, when using the User Language IN ORDER BY or FOR EACH VALUE clauses.

===DATETIME (DT) attribute===

The DATETIME attributes specifies the format of the stored data in Table B, not its function. The other date/time attributes are automatically updated fields generated at the time of record or field group creation or update. A non-automatic field can have a DATETIME format, but all the automatic date/time fields are stored in DATETIME format. The DATETIME attribute requires at least eight significant digits. 

Once you define a DATETIME value for a field, you cannot redefine the DATETIME value.

===UTF-8 and UTF-16 attributes===
Note:
The <var>UTF-8</var> and <var>UTF-16</var> attributes are available as of Model 204 version 7.5.

The <var>UTF-8</var> (or <var>UTF8</var>) attribute indicates that data is stored in [http://en.wikipedia.org/wiki/UTF-8 UTF-8] format and is treated as [[Unicode|unicode]] data inside SOUL programs. You can define a <var>UTF-8</var> field as follows:
DEFINE FIELD UTFDATA WITH [UTF-8 | UTF8]

DEFINE FIELD UTFBLOB WITH BLOB [UTF-8 | UTF8]

The <var>UTF-8</var> attribute is a constraint that rejects UTF-8 encoding of Unicode characters outside the Basic Multilingual Plane (BMP).

<var>UTF-8</var> is the only field constraint that is valid for <var>CLOB</var> or <var>BLOB</var> fields.


The <var>UTF-16</var> (or <var>UTF16</var>) attribute indicates that data is stored in [http://en.wikipedia.org/wiki/UTF-16 UTF-16] format and is treated as [[Unicode|unicode]] data inside SOUL programs. You can define a <var>UTF-16</var> field as follows:
DEFINE FIELD UTFDATA WITH [UTF-16 | UTF16]

DEFINE FIELD UTFBLOB WITH BLOB [UTF-16 | UTF16]


====Usage notes====
<ul>
<li>Since UTF-8 or UTF-16 fields behave like unicode variables in SOUL requests, printing fields with unicode characters that cannot be converted to displayable EBCDIC results in those characters being [http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references#Character_reference_overview character-entity encoded], just as they are encoded when printing unicode variables. This is also true when printing is done via a <var>[[Basic SOUL statements and commands#PRINT_ALL_INFORMATION_.28or_PAI.29_statement|PAI]]</var> statement. For example, a UTF-8 field containing the unicode value of "I like apple π" would be printed as "I like apple &#x03C0;". The ampersand symbol (<tt>&</tt>) is always encoded as &amp; when printed.</li>

<li>Just as with unicode variables, assigning an EBCDIC value to a unicode field results in the EBCDIC value being converted to unicode and then to UTF-8 or UTF-16 for storage. Simlarly, assigning a UTF-8 or UTF16 field to an EBCDIC variable results in the UTF-8 or UTF-16 value being converted to unicode and then translated to EBCDIC. In either EBCDIC to unicode or unicode to EBCDIC translation, errors result in request cancellation.

<li>Unless the preponderance of data stored in UTF-8 or UTF-16 fields has unicode values greater than U+07FF (most likely if most of the data contains Asian language characters), UTF-8 is a better choice for storing unicode data, since UTF-16 requires two bytes for every unicode character while UTF-8 only requires one byte for many common characters and only two bytes for unicode characters up to U+07FF.</li>

<li>UTF-8 and UTF-16 fields can be LOB fields or they can be STRING fields (stored in table B).</li>

<li>If a UTF-8 or UTF-16 field is defined as an OCCURS field, the length indicates the length in bytes, not the length in characters. Since UTF-8 encoding can use anywhere from one to three bytes to represent a single unicode character in the [http://en.wikipedia.org/wiki/Unicode_plane#Basic_Multilingual_Plane BMP], the only unicode characters supported by SOUL, it can be tricky using UTF-8 fields as OCCURS fields since setting the defined length requires an educated guess about the types of unicode characters that will be store in the field or (probably) oversizing a UTF-8 field to three bytes per character. In the latter case, it would make much more sense to define such a field as UTF-16 as that requires exactly two bytes for each character.</li>
</ul>

====Usage notes on mapping====
<ul>
<li>Characters outside the BMP are extremely unlikely in business applications.</li>
<li>An EBCDIC blank (X'40') is a valid UTF-8 character.</li>
<li>All numerics (X'F0' through X'F9') are UTF-8 characters for mapping characters outside the BMP. Lowercase characters generally fall into the continuation byte range and uppercase characters fall into the sequence start range. Because of this, a short, mixed case sequence, such as Tom or Bo, might slip by UFT-8 validation. However, most attempts to store EBCDIC tests into a UFT-8 field will fail, and therefore catch application errors.</li>
</ul>

====Creating UTF-8 data====
You can create <var>UTF-8</var> data using the SOUL function <var>[[$Ascii]]</var>, because 7-bit ASCII is a subset of UTF-8. For example:
ADD UTFFIELD=$ascii(?Hello?)


===VISIBLE and INVISIBLE attributes===

In general, you want to be able to retrieve, and then display or print fields, or use the field values in a report. These are fields that you want defined as VISIBLE.

If, however, you have a field that is used only to retrieve records, and space is a consideration, you might want to define the field as INVISIBLE.
Note
If the INVISIBLE attribute is not specified when the field is defined, the VISIBLE attribute is assumed. 
Using the VISIBLE attribute

Once an application retrieves a record with a User Language FIND statement or a Host Language IFFIND call, it generally processes one or more fields in User Language PRINT, NOTE, or SORT statements, arithmetic expressions, or Host Language IFGET calls. For example:
CHECK.SALARY:
IF SALARY GT 1000*AGE
THEN PRINT NAME
END IF


A field referred to by the PRINT statement must have the VISIBLE attribute in its field description. This means that the field-name-equals-value pair is actually stored in the logical record in Table B.
Using the INVISIBLE attribute

A field that has the INVISIBLE attribute, on the other hand, takes up no storage space in Table B and cannot be printed, noted, or sorted. These fields can be added, deleted, or changed in the logical record.
In a library catalog file, for example, each record can have an AUTHOR field that contains the author's full name. In addition, there can be a LAST NAME field that contains only the author's last name. This creates a convenient index to the catalog and relieves the user of the burden of knowing the entire name when making retrieval requests. Because the author's last name already is part of the (VISIBLE) AUTHOR field, some space can be saved in Table B by selecting the INVISIBLE attribute for LAST NAME.
Reorganizing INVISIBLE fields

Because INVISIBLE fields are not stored in Table B, they require special care if the file is ever reorganized. When designing a file, be sure to take reorganization requirements for these fields into consideration. See the File reorganization and table compaction page, [[File reorganization and table compaction#Reorganizing INVISIBLE fields|Reorganizing INVISIBLE fields]] section for more information. 
Maintaining INVISIBLE fields

INVISIBLE fields must also have the KEY, NUMERIC RANGE, or ORDERED attribute, and they are normally used only to retrieve records. 

The User Language FILE RECORDS statement and the Host Language Interface IFFILE function can be used to rapidly add an INVISIBLE KEY field name = value pair to an entire set of records. For example:
ALL.RECS: FIND ALL RECORDS FOR WHICH
NAME = SMITH OR SMYTHE OR SMYTH
END FIND
FILE: FILE RECORDS IN ALL.RECS UNDER HOMONYM = SMYTH


<var class="product">Model 204</var> makes entries in Tables C and D to allow retrievals with the specification HOMONYM = SMYTH but does not change Table B. For further information about adding, changing, or deleting INVISIBLE fields, see the SOUL description of the <var>[[Field attributes#INVISIBLE attribute|INVISIBLE]]</var> attribute.
Table B considerations

The values of VISIBLE fields can be stored in the logical record in Table B in one of four formats depending upon the selection of STRING/BINARY, CODED/NON-CODED, or FLOAT field attributes. The choice affects space requirements and, except for a slight increase in the time required for updates and some types of retrievals (see [[#CODED and NON-CODED attributes|CODED and NON-CODED attributes]]), is transparent to the user. 

The values of fields that have the INVISIBLE attribute are not stored in Table B, and physical storage attributes cannot be specified in their descriptions. 
Using INVISIBLE fields in 1NF files

The First-Normal form relational model cannot be enforced for INVISIBLE fields. However, INVISIBLE fields are useful within <var class="product">Model 204</var> for list processing and to support SQL multicolumn keys (see the <var class="product">Model 204</var> SQL Server User's Guide for more information). Therefore, the INVISIBLE field attribute is allowed, but INVISIBLE fields are not mapped to SQL-accessible columns, and there are other limitations with SQL DML operations against INVISIBLE fields, as described in the SQL Server User's Guide. The following rules and restrictions apply to INVISIBLE fields in 1NF files:

<ul>
<li>Because the INVISIBLE and AT-MOST-ONE attribute are incompatible, INVISIBLE fields must be defined as REPEATABLE.</li>

<li>You cannot REDEFINE a field as INVISIBLE within a 1NF file; the INVISIBLE and REPEATABLE attributes can be specified only with a DEFINE command. In the case of a record security key field, use the INITIALIZE command to specify the field as INVISIBLE and REPEATABLE.</li>

<li>INVISIBLE fields in 1NF files must also be ORDERED or KEY (NUMERIC RANGE is not legal in a 1NF file and results in an error message). </li>
</ul>

Compatibility with other attributes

The INVISIBLE attribute cannot be specified for a field defined with the FLOAT or AT-MOST-ONE attributes.

==Data content==

In addition to the data type (above), there are additional attributes which further control how the data is stored and manipulated:
<ul>
<li>CODED, NON-CODED </li>
<li>OCCURS</li>
<li>LENGTH</li>
<li>PAD</li>
<li>FEW-VALUED, MANY-VALUED </li>
<li>UPDATE IN PLACE, UPDATE AT END</li>
<li>DEFAULT-VALUE</li>
<li>STORE-DEFAULT, STORE-NULL</li>
<li>AT-MOST-ONE, REPEATABLE and EXACTLY-ONE</li>
<li>DEFERRABLE/NON-DEFERRABLE</li>
</ul>

===CODED and NON-CODED attributes===

The CODED and NON-CODED attributes let you choose between saving disk space (with CODED) or speeding up update and retrieval time (with NON-CODED). This section discusses how these attributes work.
Note:
If the CODED attribute is not specified when a field is defined, the NON-CODED attribute is assumed.
NON-CODED attribute

If a field is designated NON-CODED without an OCCURS clause (see the following discussion), its value is stored in Table B as a simple character string that has an additional byte to indicate its length. 

NON-CODED is the best choice for any field whose values have an average length of 1-3 bytes whether or not they are compressible numbers.
CODED attribute

Choose the CODED option to save Table B space where the values of the field are not suitable for BINARY compression and where their average length is four or more characters.

When a value that has the CODED attribute is defined, the character string is stored in Table A-the internal file dictionary-and a 4-byte value code pointing to that character string is stored in the logical record in Table B. Space is saved when there are several records that contain the same value. The string is stored only once in Table A, and only the 4-byte code is stored in each of the several records in Table B.

Choosing CODED vs. NON-CODED

The coding and decoding of these value codes takes time, which can slow down updates and retrievals. If speed is important and if disk space is relatively plentiful, do not choose the CODED attribute.

If disk space is somewhat tight, choose the CODED attribute for fields where the values are long and where there are a small number of values relative to the number of records in the file. A STATE field is a prime example.

A more precise rule governing the choice of the CODED attribute is difficult to arrive at since first it must be determined (based on the number and length of the field values, and on the number of records) if any disk space is actually saved by the CODED attribute. Then, any space saved must be weighed against the extra time taken by CODED retrievals. And the relative importance of disk space and time are likely to vary with the application as well as with the installation.

The formulas in [[File size calculation in detail]] show more explicitly the effects of the CODED field attribute on Table A and B size.

Field value encoding is entirely transparent to the user. Data is returned exactly as it was entered. Codes are system-generated, internal codes that have no meaning to a user. 


<div id="Preallocated fields"></div><div id="OCCURS attribute"></div>

===Preallocated fields (OCCURS attribute)===

Any VISIBLE field can be a preallocated field. However, a VISIBLE field that appears a fixed number of times in most of the records in a file, with fairly uniform lengths for the values, is most suited for preallocation in Table B. Preallocated fields, if selected appropriately, require less Table B space than other fields and can be updated and retrieved slightly faster. 

Preallocation means that space is reserved in each new record added to a file. As occurrences of preallocated fields are stored in a record, they are placed in the reserved space. Space is used even for occurrences that have not been stored, whereas non-preallocated fields use no space for missing occurrences. Preallocation also imposes restrictions on the number and length of values that can be stored in a record. A field is preallocated if its description includes an OCCURS clause. 

[[File size calculation in detail]] provides specific rules for the amount of space used by preallocated and non-preallocated fields. Use these rules to determine whether or not to preallocate a particular field. 
Using an OCCURS clause

A field is preallocated if its description includes an OCCURS clause. The OCCURS clause indicates the number of occurrences of the field that are preallocated or reserved in each Table B record. From 1 to 255 occurrences can be specified. Any number of values, up to the specified limit, <var class="term">n</var>, can be stored in the record.

Only as many occurrences as have been stored can be retrieved. Space allocated for unstored values is wasted. 

If OCCURS is not included in a field description, the field still can occur more than once in a record. Space for the occurrences is not preallocated. There is no limit to the number of values that can be stored for a non-preallocated field.
Restrictions for preallocated fields

The OCCURS option can be specified only for fields that can be preallocated with a fixed length in Table B. This includes only fields that are defined as CODED, BINARY, or LENGTH <var class="term">m</var> (see [[#LENGTH and PAD clauses|LENGTH and PAD clauses]]). If a field is defined as BINARY but does not contain an OCCURS clause, values that cannot be compressed to a binary representation still can be stored in the field. If a field is defined as both BINARY and OCCURS, only compressible values can be stored in it. 

<var class="product">Model 204</var> does not allow incompressible values to be stored in such fields. To avoid such compression problems, include CODED with BINARY and OCCURS in the field description. 
Displaying the set of preallocated fields

The <var>[[DISPLAY RECORD command|DISPLAY RECORD]]</var> command will show all of the preallocated fields in a file. This information is stored on a page in [[Table D (File architecture)|Table D]] where it is used to create the preallocated field space at the beginning of a record when it is initially stored. 
Note:
Because <var class="product">Model 204</var> cannot distinguish values padded with X'00' from zero-length values explicitly stored in the file, <var class="product">Model 204</var> does not allow zero-length values to be explicitly stored in preallocated fields. 


OCCURS cannot be specified on a field group field.

===LENGTH and PAD clauses===
Using the LENGTH clause

Use the LENGTH clause to specify the length of FLOAT fields, as well as NON-CODED preallocated (OCCURS) string fields. 
LENGTH must be specified for NON-CODED preallocated string fields: the LENGTH must be included in the description of a NON-CODED preallocated string field to set the maximum length of the field. The length must be in the range 1 through 255. The specified length is preallocated for the number of occurrence specified by the OCCURS clause. 

LENGTH with FLOAT fields: LENGTH is required with FLOAT to indicate the precision of the floating-point field being defined. The LENGTH options in this instance are 4, 8, or 16. (See [[#FLOAT attribute|FLOAT attribute]].)
Specifying the LENGTH clause: The LENGTH clause limits the length of values that can be stored in the field. <var class="product">Model 204</var> does not store values that are longer than the specified length. The LENGTH clause does not impose any minimum length. Values that are shorter than the specified length are padded with the PAD character to the maximum length as they are stored in Table B and are returned to their original length as they are retrieved. See the description of padding in [[#LENGTH and PAD clauses|LENGTH and PAD clauses]]. 

Field occurrences that have been preallocated but not stored contain zero-length values. 

Using the PAD clause

You can include a PAD clause in a field description to select the character that is used to pad field values that are shorter than the length specified in the LENGTH clause (see [[#LENGTH and PAD clauses|LENGTH and PAD clauses]]) for the field. If no PAD character is specified in a field description, the default character, X'00', is used.

Padding characters are invisible to the user and are not included in a retrieved value. Make sure that the padding character does not appear as part of a field value. If it does, incorrect results can occur.

===FEW-VALUED and MANY-VALUED attributes===

If a field that has the CODED or FRV attribute is expected to take on fewer than about 50 different values, choose the FEW-VALUED attribute. Otherwise, define the field as MANY-VALUED. 

This option determines whether the value string is stored in the FEW-VALUED or MANY-VALUED section of Table A, and is invalid for fields that are neither CODED nor FRV. Keep the number of values stored in the FEW-VALUED section small to ensure that this section is kept in core during retrieval and update operations. This practice reduces the number of disk accesses and increases retrieval speed. 
Note:
If the FEW-VALUED attribute is not specified when a field is defined, the MANY-VALUED attribute is assumed.

===UPDATE IN PLACE (UP) and UPDATE AT END (UE) attributes===

<var class="product">Model 204</var> provides the following field attributes that control the way that the value of a field occurrence is changed in Table B:
<table>
<tr class="head">
<th>
If this attribute is specified...</th>
<th>Then a change in the value of a field
occurrence...</th>
</tr>

<tr>
<td>UPDATE IN PLACE </td>
<td>

Does not change its position relative to other occurrences of the same field in Table B.

This attribute is the default.
</td>
</tr>

<tr>
<td>UPDATE AT END</td>
<td>Is accomplished by deleting the existing occurrence and adding a new one following the others. </td>
</tr>
</table>
Choosing an update option

Specify either of these options as part of a field description. The UPDATE AT END approach can be useful in certain data aging applications: for example, in applications in which the first occurrence of a field represents the oldest update to the file, and the last occurrence is the most recent update. UPDATE IN PLACE generally is more efficient.

The choice of update option determines the position of a field occurrence within a record only in relation to other occurrences of the same field. The ordering of different fields within a record is determined by a variety of factors, of which the update method is only one. The order of fields within a record normally is not under the control of the file manager.

SOUL update statements other than <var>CHANGE</var> are not affected by the choice of an update option. The <var>ADD</var> and <var>STORE</var> statements always cause values to be added as the last occurrences in a record. The <var>DELETE</var> statement always removes the deleted value while maintaining the relative ordering of the remaining occurrences. 

Compatibility with other attributes

The values of fields that have the <var>INVISIBLE</var> attribute are not stored in Table B, and <var>UPDATE IN PLACE</var> or <var>UPDATE AT END</var> cannot be specified in their descriptions. 

===DEFAULT-VALUE (DV) attribute===
<var>DEFAULT-VALUE</var> specifies the value of the field if the value was not explicitly added in the <var>STORE RECORD</var>, <var>ADD FIELDGROUP</var>, or <var>INSERT FIELDGROUP</var> initial data block.

A field defined with a <var>DEFAULT-VALUE</var> (<var>DV</var>) attribute value:
<ul>
<li>Must also be defined with the <var>EXACTLY-ONE</var> or the <var>AT-MOST-ONE</var> attribute. </li>

<li>Must be contained in a file that has the <var>[[FILEORG parameter|FILEORG]]</var> parameter X'100' bit set. </li>
</ul>

The <var>DEFAULT-VALUE</var> attribute is available as of Model 204 version 7.5. For more information about <var>DEFAULT-VALUE</var> fields that are members of a field group, see [[Processing multiply occurring fields and field groups#Handling references to missing occurrences|Handling references to missing occurrences]]. 

The value of the <var>STORE-DEFAULT</var> attribute determines whether the <var>DEFAULT-VALUE</var> is physically stored on the record or if it is just used as the default value when the field is missing:
<table class="thJustBold">
<tr class="head"><th>STORE-DEFAULT value</th><th>Effect on record storage</th></tr>

<tr><th>ALL</th><td>Always store the <var>DEFAULT-VALUE</var> on the record.</td></tr>
<tr><th>NONE</th><td>Never store the <var>DEFAULT-VALUE</var> on the record.</td></tr>
<tr><th>LITERAL</th><td>Store the <var>DEFAULT-VALUE</var> if it was literally entered on the store statement (not entered as a variable).</td></tr>
</table>

<var>STORE-NULL</var> has the same options as <var>STORE-DEFAULT</var>, but they are applied to storing nulls:

<table class="thJustBold">
<tr class="head"><th>STORE-NULL value</th><th>Effect on null storage</th></tr>

<tr><th>ALL</th><td>Always store a null value on the record.</td></tr>
<tr><th>NONE</th><td>Never store a null value on the record.</td></tr>
<tr><th>LITERAL</th><td>Store the null value if it was literally entered on the Store statement (not entered as a variable).</td></tr>
</table>

Note: Neither <var>STORE-NULL NONE</var> nor <var>STORE-NULL LIT</var> is allowed with <var>DEFAULT-VALUE</var>.

The <var>DEFAULT-VALUE</var> attribute allows values as long as 31 bytes. An attempt to use more results in:
M204.2851: DEFAULT-VALUE VALUE
'1234567890123456789012345678901234567890' TOO BIG, MUST BE <32 BYTES

Note: The minimum length of a <var>DEFAULT-VALUE</var> value is 1 byte. A null string value is not allowed. 

The value of <var>DEFAULT-VALUE</var> is not constrained by attributes such as <var>LEQ</var>, <var>LLE</var>, and <var>LGE</var>.
For example, the entire default value is returned for a field that has been added, even if it exceeds the <var>LEQ</var> setting.


===STORE-DEFAULT (SD) and STORE-NULL (SN) attributes===
The <var>STORE-DEFAULT</var> and <var>STORE-NULL</var> attributes specify whether to physically store the default value and the null value, respectively, for the field in each record. These attributes are available as of Model 204 version 7.5.

You can redefine the <var>STORE-DEFAULT</var> and/or <var>STORE-NULL</var> attribute values.

Note: A field with the <var>STORE-DEFAULT</var> attribute must also have the <var>DEFAULT-VALUE</var> attribute.

The <var>STORE-DEFAULT</var> and <var>STORE-NULL</var> attributes offer these options:
<ul>
<li><var>LITERAL</var> (the default)</li>
<li><var>NONE</var></li>
<li><var>ALL</var></li>
</ul>

====STORE-DEFAULT example====

The following example shows the effect of <var>DEFAULT-VALUE</var> on fields defined with the different <var>STORE-DEFAULT</var> types (<var>ALL</var>, <var>NONE</var>, and <var>LITERAL</var>).
Field <code>NAME_SD_NONE</code> is defined with the <var>STORE-DEFAULT</var> option <var>NONE</var>, field <code>NAME_SD_LIT</code> with the option <var>LITERAL</var>, and field <code>NAME_SD_ALL</code> with the option <var>ALL</var>. The <var>DEFAULT-VALUE</var> for all of the fields is <code>NONAME</code>. 

In this example, the fields belong to a field group, but the <var>STORE-DEFAULT</var> (and <var>STORE-NULL</var>) attribute can also be assigned to a field that is not part of a field group. The only requirement is that the field cannot be defined as <var>REPEATABLE</var>; that is, it must be <var>AT-MOST-ONE</var> or <var>EXACTLY-ONE</var>.
DEFINE FIELDGROUP X
DEFINE FIELD NAME_SD_NONE WITH FIELDGROUP X AND ORD AT-MOST-ONE -
STORE-DEFAULT NONE DEFAULT-VALUE 'NONAME'

DEFINE FIELD NAME_SD_LIT WITH FIELDGROUP X AND ORD AT-MOST-ONE -
STORE-DEFAULT LITERAL DEFAULT-VALUE 'NONAME'

DEFINE FIELD NAME_SD_ALL WITH FIELDGROUP X AND ORD AT-MOST-ONE -
STORE-DEFAULT ALL DEFAULT-VALUE 'NONAME'


There are basically two ways to store a field in a record: 
<ul>
<li>Using a literal:
STORE RECORD
FIELD.A = 'ABC'
END STORE
</li>

<li>Using a variable:
%X = 'ABC'
STORE RECORD
FIELD.A = %X
END STORE
</li>
</ul>

Additionally, a field might simply be missing (in the following example, the record has a <code>FIELD.B</code>, but <code>FIELD.A</code> is missing):
STORE RECORD
FIELD.B = 'XXX'
END STORE


The <var>STORE-DEFAULT</var> options determine how the field will be physically stored if the <var>DEFAULT-VALUE</var> is stored in the field. 

This example shows what is physically stored in the record when the <var>DEFAULT-VALUE</var> is stored for each of the fields defined above for <code>FIELDGROUP X</code>. The <var>DEFAULT-VALUE</var> defined for each is <code>NONAME</code>. First, the actual <var>DEFAULT-VALUE</var> of <code>NONAME</code> is added by using a variable, then by using the literal <code>'NONAME'</code>. Then a field group occurrence is added where the field is missing. 
ADD.X: SUBROUTINE
IN FILEX FOR RECORD NUMBER %CURREC
* add first field group occurrence using the variable %NAME:
%NAME='NONAME'
ADD FIELDGROUP X
NAME_SD_NONE = %NAME
NAME_SD_LIT = %NAME
NAME_SD_ALL = %NAME
END ADD
* add second field group occurrence using the literal 'NONAME':
ADD FIELDGROUP X
NAME_SD_NONE = 'NONAME'
NAME_SD_LIT = 'NONAME'
NAME_SD_ALL = 'NONAME'
END ADD
* add third occurrence of the field group with all values missing:
ADD FIELDGROUP X
* none of these fields added to this occurrence
END ADD
END FOR


A subsequent <var>PAI</var> of the field group shows what is physically stored on the record: 
<table>
<tr class="head">
<th>The field defined with... </th>
<th>is...</th>
</tr>

<tr>
<td>STORE-DEFAULT NONE </td>
<td>Never stored on the record. </td>
</tr>

<tr>
<td>STORE-DEFAULT ALL </td>
<td>Always stored on the record. </td>
</tr>

<tr>
<td nowrap>STORE-DEFAULT LITERAL </td>
<td>Not stored in the first occurrence, because a %variable was used. It was stored in the second occurrence, because the field was added using a literal string.</td>
</tr>
</table>

The <var>PAI</var> output: 
\X = 1
NAME_SD_ALL = NONAME
/X = 1
\X = 2
NAME_SD_LIT = NONAME
NAME_SD_ALL = NONAME
/X = 2
\X = 3
/X = 3

<blockquote class="note">
Note:
When the record above is printed (using the following):
FR
PRINT '# NAME_SD_NONE: NAME_SD_LIT: NAME_SD_ALL:'
FEO:
FEO FIELDGROUP X
PRINT OCCURRENCE IN FEO AND NAME_SD_NONE AND -
NAME_SD_LIT AT 16 AND NAME_SD_ALL AT 30
END FOR
END FOR


The <var>DEFAULT-VALUE</var> is printed whether the field is physically stored on the record or not.

# NAME_SD_NONE: NAME_SD_LIT: NAME_SD_ALL:
1 NONAME NONAME NONAME
2 NONAME NONAME NONAME
3 NONAME NONAME NONAME

Note: The same behavior occurs whether the field is <var>AT-MOST-ONE</var>, as in this example, or <var>EXACTLY-ONE</var>. However, within fieldgroup context, a <var>PAI</var> of an <var>EXACTLY-ONE</var> field always shows a value. The actual physical storage on the record is the same for both attributes. 
</blockquote>

====STORE-NULL example====

The options on the <var>STORE-NULL</var> attribute react similarly to those of <var>STORE-DEFAULT</var>. When the fields are defined as follows:
DEFINE FIELDGROUP X
DEFINE FIELD NAME_SN_NONE WITH FIELDGROUP X AND ORD AT-MOST-ONE -
STORE-NULL NONE
DEFINE FIELD NAME_SN_LIT WITH FIELDGROUP X AND ORD AT-MOST-ONE -
STORE-NULL LITERAL
DEFINE FIELD NAME_SN_ALL WITH FIELDGROUP X AND ORD AT-MOST-ONE -
STORE-NULL ALL


And the code used to store the field groups is:
IN FILEX [[Record loops#FOR RECORD NUMBER processing|FRN]] %CURREC
* add first occurrence using the variable %NAME:
%NAME=''
ADD FIELDGROUP X
NAME_SN_NONE = %NAME
NAME_SN_LIT = %NAME
NAME_SN_ALL = %NAME
END ADD
* add second occurrence using the literal '':
ADD FIELDGROUP X
NAME_SN_NONE = ''
NAME_SN_LIT = ''
NAME_SN_ALL = ''
END ADD
* add third occurrence with missing values:
ADD FIELDGROUP X
END ADD
END FOR


The resulting <var>PAI</var> is:
\X = 1
NAME_SN_ALL =
/X = 1
\X = 2
NAME_SN_LIT =
NAME_SN_ALL =
/X = 2
\X = 3
/X = 3


And this request: 
BEGIN
FR
PRINT '# NAME_SN_NONE: NAME_SN_LIT: NAME_SN_ALL:'
FEO:
FEO FIELDGROUP X
PRINT OCCURRENCE IN FEO AND -
NAME_SN_NONE AND NAME_SN_LIT AT 18 -
AND NAME_SN_ALL AT 32
END FOR
END FOR
END


Results in nulls displayed for each field:
# NAME_SN_NONE: NAME_SN_LIT: NAME_SN_ALL:
1
2
3


===AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes===

You can use the AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes, which are mutually exclusive, to define an individual field or a field that is part of a field group definition. 
Note: The EXACTLY-ONE attribute is available as of Model 204 version 7.5.

====Using the AT-MOST-ONE attribute====

The AT-MOST-ONE attribute allows you to ensure that there is only one occurrence of a field in any record, without preallocating space for the field. 

In addition, the AT-MOST-ONE attribute is required for fields in First-Normal Form (1NF) files. AT-MOST-ONE and REPEATABLE fields in 1NF files are discussed in this section.
Note:
In non-1NF files, if the AT-MOST-ONE attribute is not specified when a field is defined, the REPEATABLE attribute is assumed. 

If a field is defined with the AT-MOST-ONE attribute, <var class="product">Model 204</var> prevents multiple occurrences of that field in any given record. The AT-MOST-ONE attribute is useful if, for example, you know that there will be one variable-length field per record, or if you have a field that is often left blank but does not have more than one value per record (such as SPOUSE NAME). 

Unlike fields with the OCCURS attribute, AT-MOST-ONE fields are not specifically preallocated. The AT-MOST-ONE attribute lets you store these kinds of records without wasting the space required by OCCURS.
Using the REPEATABLE attribute

If a field is not defined as AT-MOST-ONE, then it is REPEATABLE. Fields with the REPEATABLE attribute can accept multiple occurrences of the field in the record. Unlike the OCCURS attribute, REPEATABLE does not preallocate fields, nor does REPEATABLE let you specify the number of occurrences of the field.

====Using the EXACTLY-ONE (EXONE) attribute====

As the name suggests an EXACTLY-ONE attribute in a field definition means that the field always has exactly one occurrence in its record or field group context after the initial data block for the record or field group (STORE RECORD, ADD FIELDGROUP, or INSERT FIELDGROUP). If no explicit value is stored for the field, its value has either the DEFAULT-VALUE for the field or the null string (''), if no DEFAULT-VALUE was specified for the field.

You cannot add, insert, or delete an EXACTLY-ONE field, although you can change an EXACTLY-ONE field. 

The EXACTLY-ONE attribute that also has the DEFAULT-VALUE attribute will conflict with the STORE-NULL NONE attribute.

The EXACTLY-ONE attribute is also not allowed with the STORE-NULL LITERAL attribute.

====EXACTLY-ONE fields with a field group====

The <var>EXACTLY-ONE</var> attribute for a field within a field group means that the field can occur only once inside a single field group occurrence. However, since field groups can occur multiple times in a field group record, an <var>EXACTLY-ONE</var> field inside a field group can occur multiple times inside a field group record. 

For more information about <var>EXACTLY-ONE</var> fields in a field group, see [[Processing multiply occurring fields and field groups#Updating fields in a field group|Updating fields in a field group]]. 

====Defaults for AT-MOST-ONE, REPEATABLE and EXACTLY- ONE fields====

REPEATABLE is the default except for 1NF files, where AT-MOST-ONE is required on all fields, except INVISIBLE. See [[#VISIBLE and INVISIBLE attributes|VISIBLE and INVISIBLE attributes]] for information. 

The AT-MOST-ONE attribute is required on all fields in a 1NF file because multiply occurring fields violate relational First-Normal Form. The one exception to this rule is for INVISIBLE/REPEATABLE fields in 1NF files. See [[#AT-MOST-ONE in First Normal Form .281NF.29 files|AT-MOST-ONE in First Normal Form files]] for more information.

The EXACTLY-ONE attribute is the default frequency of occurrence for a field defined within a field group.

====Enforcing AT-MOST-ONE constraints====

<var class="product">Model 204</var> ensures that AT-MOST-ONE field constraints are not violated for the following User Language requests and the Host Language and FLOD counterparts: 
<ul>
<li>ADD</li>
<li>INSERT</li>
<li>STORE RECORD</li>
</ul>

Before the indexes are updated and a new field is added or inserted into the <var class="product">Model 204</var> record, all existing fields in the record are checked to ensure that the new field does not create a second occurrence: 

<ul>
<li>If a new field violates the AT-MOST-ONE rules, and there is no ON FCC unit, the request is canceled with the following error message:
M204.2119: AT-MOST-ONE CONSTRAINT VIOLATION IN RECORD <var class="term">recordnumber</var>, FIELD IGNORED: <var class="term">fieldname</var>=<var class="term">value</var>
</li>

<li><var class="product">Model 204</var> validates a field if you REDEFINE it to be AT-MOST-ONE.</li>

<li>If a violation occurs and there is an ON FCC unit, <var class="product">Model 204</var> processes the ON unit. </li>
</ul>

In the Host Language Interface, the 202 return code is passed back to <var class="product">Model 204</var>; in FLOD, the file is marked logically inconsistent. However, <var class="product">Model 204</var> does not cancel the request in either case. 

====AT-MOST-ONE and transaction back out files====

Transaction back out must be active for files when defining AT-MOST-ONE fields. If you try to define an AT-MOST-ONE field in a non-TBO file, the DEFINE fails and you receive an error message. 

Once the field is defined, you can turn Transaction back out off in non-1NF files. However, <var class="product">Model 204</var> customer support strongly recommends that you keep Transaction back out set in files containing fields that can cause constraint conflicts (currently AT-MOST-ONE and UNIQUE). If you turn Transaction back out off in a file with an AT-MOST-ONE or UNIQUE field, <var class="product">Model 204</var> sends you a warning message and a "Do You Really Want To?" prompt.

====Using FLOD or FILELOAD with AT-MOST-ONE fields====

When you use FLOD or FILELOAD to load or modify records that have AT-MOST-ONE fields, <var class="product">Model 204</var> ensures that the new or modified records do not violate AT-MOST-ONE constraints. <var class="product">Model 204</var> detects and reports all violations of AT-MOST-ONE in one pass of the input data. If <var class="product">Model 204</var> finds any fields that violate the constraints, the following occurs:
<ol>
<li>The error is reported and the new or duplicate field is rejected.</li>

<li>FLOD continues processing the input data.</li>

<li>At the end of the run, the file is marked "logically inconsistent;" that is, the FISTAT parameter is set to X'40'. See [[File integrity and recovery#Logically inconsistent files|Logically inconsistent files]] for more information.</li>

<li>The following error message is issued for each violation:
M204.2119: AT-MOST-ONE CONSTRAINT VIOLATION IN RECORD <var class="term">recordnumber</var>, FIELD IGNORED: <var class="term">fieldname</var>=<var class="term">value</var>
</li>
</ol>

====AT-MOST-ONE in First Normal Form (1NF) files====
Using OCCURS 1 in 1NF files: For 1NF files, where AT-MOST-ONE is required, use OCCURS 1 to save processing time if you are storing a large number of records in which the field is always exactly the same length (such as a Social Security Number). 

INVISIBLE fields in 1NF files: The First-Normal form relational model cannot be enforced for INVISIBLE fields. However, they are useful within <var class="product">Model 204</var> for list processing and to support SQL multicolumn keys. (See the <var class="product">Model 204</var> SQL Server User's Guide for more information.) Therefore, the INVISIBLE field attribute is allowed, but INVISIBLE fields are not mapped to SQL-accessible columns. The following rules and restrictions apply to INVISIBLE fields in 1NF files:

<ul>
<li>Because the INVISIBLE and AT-MOST-ONE attributes are incompatible, INVISIBLE fields must be defined as REPEATABLE.</li>

<li>You cannot REDEFINE a field as INVISIBLE within a 1NF file; you can specify the INVISIBLE and REPEATABLE attributes only with a DEFINE command. In the case of a record security key field, specify the field as INVISIBLE and REPEATABLE using the INITIALIZE command.</li>

<li>INVISIBLE fields in 1NF files must also be ORDERED or KEY. NUMERIC RANGE is not legal in a 1NF file and results in an error message)</li>
</ul>

====Defining AT-MOST-ONE and REPEATABLE fields in non-1NF files====

You can DEFINE or REDEFINE a field to be AT-MOST-ONE in any non-1NF <var class="product">Model 204</var> file created after Release 9.0. 

When redefining a field to AT-MOST-ONE that does not currently have the OCCCURS 1 attribute, <var class="product">Model 204</var> scans Table B to verify that no multiple occurrences of the field exist in any record. If any field violates the AT-MOST-ONE constraints, the REDEFINE fails and the following error message is displayed for each violation:
M204.2122: AT-MOST-ONE CONSTRAINT VIOLATION FOR FIELD fieldname IN RECORD recordnumber


====Using the AT-MOST-ONE or the OCCURS 1 attribute====

Although both the AT-MOST-ONE and OCCURS 1 attributes prevent more than one occurrence of a field in a record, they achieve their goal in different ways. For non-1NF files, use either the AT-MOST-ONE or the OCCURS 1 attribute. Using both causes redundant processing. Understanding the advantages of each should help you decide which attribute you want to use. 

AT-MOST-ONE attribute:

<ul>
<li>Does not preallocate the field. Therefore, if the field values between records are of very different lengths or if you do not know the length of the longest record, use AT-MOST-ONE.</li>

<li>Allows you to correct violations before the record is stored with the ON FCC unit. If you do not use an ON FCC unit, then a constraint violation cancels the request. Therefore, if it is important to allow users to correct violations, or it is important that the request not be canceled, use AT-MOST-ONE.</li>
</ul>

OCCURS 1 attribute:
<ul>
<li>Preallocates space for the field in every record. If you are storing a large number of records and the length of the value is generally the same, pre-allocating the field with OCCURS 1 can save you processing time. </li>

<li>Cancels the request when a violation occurs. With OCCURS 1, you cannot use an ON FCC unit to correct violations. </li>
</ul>

====Compatibility with other field attributes====

AT-MOST-ONE is not compatible with the following field attributes:
<ul>
<li>INVISIBLE</li>
<li>OCCURS greater than 1</li>
<li>REPEATABLE

REPEATABLE is compatible with all field attributes except AT-MOST-ONE.
</li>
</ul>

===Coordinating AT-MOST-ONE and UNIQUE attributes===

Both AT-MOST-ONE and UNIQUE are examples of field-level constraints. Although the function of the UNIQUE and AT-MOST-ONE attributes appear similar, their actual operations differ:

<table>
<tr class="head">
<th>This attribute</th>
<th>Affects...</th>
</tr>

<tr>
<td>UNIQUE</td>
<td>Value of the field</td>
</tr>

<tr>
<td>AT-MOST-ONE</td>
<td>Number of fields per record</td>
</tr>
</table>

For example, if a Social Security field within an EMPLOYEE file is both UNIQUE and AT-MOST-ONE:
<table>
<tr class="head">
<th>This attribute</th>
<th>Ensures that...</th>
</tr>

<tr>
<td>UNIQUE</td>
<td>Social security number for every employee is different.</td>
</tr>

<tr>
<td>AT-MOST-ONE</td>
<td>Each employee has only one social security number. </td>
</tr>
</table>

Coordinating the use of the AT-MOST-ONE and the UNIQUE attributes increases the integrity and accuracy of your records.

===DEFERRABLE and NON-DEFERRABLE attributes===

The DEFERRABLE and NON-DEFERRABLE attributes let you specify whether the updates to the index (Tables C and D) for a KEY ORDERED field can be deferred; that is, stored or updated at a later time.

The DEFERRABLE attribute is recommended and is the default.
Note:
If the NON-DEFERRABLE attribute is not specified when a field is defined, the DEFERRABLE attribute is assumed.

====Choosing between DEFERRABLE and NON-DEFERRABLE====

Under normal circumstances, the storing and updating of records in the <var class="product">Model 204</var> file is done all at once. That is, Tables B, C, D, E, and X are changed simultaneously. When there is a high volume of updates (for example, a Batch2 process adding large numbers of records), efficiency and space reductions can be gained by deferring the updates to Tables C and D.

Under some circumstances, it might be necessary to override this deferral of updates to the index for particular fields. For instance, consider a situation in which new records are added Online to a personnel file. You might be willing to wait a day for the ability to retrieve the new records. The updates to Tables C and D are deferred until a batch processing window (and the application of deferred updates does require exclusive access to the file), when they are done in a batch run. However, when adding new records, you want to ensure that a record containing a duplicate Social Security number (for example) is not added to the file. 

You can define the Social Security number field as NON-DEFFERABLE and write a procedure to retrieve any records already in the file that have the new Social Security number and display an error message if one is found. If updates to the index on this field have been deferred, you would not find a duplicate added earlier in the same day. By selecting the NON-DEFERRABLE attribute for the Social Security number field, you can ensure that Tables C and D are updated immediately. 
Note:
To provide immediate updating in BATCH204 runs, special action must be taken. See "Overriding deferred updates" for more information.

You can also detect duplicate Social Security numbers by defining the field with the UNIQUE and ORDERED attributes. See [[#UNIQUE and NON-UNIQUE attributes|UNIQUE and NON-UNIQUE attributes]].

====Compatibility with other attributes====

The DEFERRABLE/NON-DEFERRABLE attribute is invalid for a field that has these attributes: BLOB, CLOB, NON-KEY, NON-ORDERED, and NON-RANGE. 

For a table showing invalid attribute combinations, see the [[DEFINE FIELD command]]. If you are defining field attributes with FILEMGMT, you will not be allowed to specify conflicting attributes. 

<div id="Field Constraints">

==Field and content constraints==
You can set up constraints to prevent "invalid" updates to the file. The updates might be invalid because to permit them would violate rules about the field (a second occurrence to an AT-MOST-ONE field, for example). Or you can set up "content" constraints to prevent values outside of those permitted to be stored.

In addition, you can use the [[#LEVEL attribute|LEVEL attribute]] to prevent use of a field by unauthorized users.

===Field constraints===

====ON FIELD CONSTRAINT CONFLICT (ON FCC) unit====

To help control processing with UNIQUE and AT-MOST-ONE fields, use the User Language ON FCC unit. ON FCC is invoked whenever a field-level constraint conflict, such as an attempt to add a second occurrence of an AT-MOST-ONE field.

An ON FCC unit is used with a number of $functions that can help you determine exactly where the field constraint conflict has occurred. The $UPDSTAT function is discussed below. Refer to the SOUL wiki pages for information on [[Subroutines#ON_units_2|other $functions for ON FCC.]]

$UPDSTAT function

The $UPDSTAT function is used in conjunction with the ON FIELD CONSTRAINT CONFLICT unit and field attributes which have field-level constraints of UNIQUE and AT-MOST-ONE. You <var class="term">must</var> use $UPDSTAT in the ON FCC unit when writing procedures for files that have (or might have in the future) more than one type of field-level constraint defined.

If $UPDSTAT is invoked from an ON FCC unit following the detection of a field-level constraint conflict, it returns a numeric value denoting the type of conflict that has occurred:

<table>
<tr class="head">
<th>Value</th>
<th>Meaning </th>
</tr>

<tr>
<td align="right">0 </td>
<td>No violation occurred</td>
</tr>

<tr>
<td align="right">1 </td>
<td>Uniqueness violation occurred</td>
</tr>

<tr>
<td align="right">2 </td>
<td>AT-MOST-ONE violation occurred </td>
</tr>
</table>

The $UPDSTAT function takes no arguments. 

See information about the [[#AT-MOST-ONE and REPEATABLE attributes|AT-MOST-ONE and REPEATABLE attributes]].
UNIQUE and ORDERED fields

Because <var class="product">Model 204</var> uses the Ordered Index to process UNIQUE values, fields defined as UNIQUE must also be defined as ORDERED. For more information about the Ordered Index see [[#ORDERED and NON-ORDERED attributes|ORDERED and NON-ORDERED attributes]].

====UNIQUE and NON-UNIQUE attributes====

Defining a field with the UNIQUE attribute allows <var class="product">Model 204</var> to ensure that a given field name = value pair occurs only once in a file. A Social Security number field is one example that might benefit from having the UNIQUE attribute. The UNIQUE attribute specifies that there can be only one occurrence of a field in the file. Multiple occurrences are not allowed.

When storing a field specified as UNIQUE, <var class="product">Model 204</var> first queries the Ordered Index, looking for an identical field-name-equals-value pair. If it finds an identical value, <var class="product">Model 204</var> issues an error message and does not perform the update. This is true both within a record for multiply occurring fields and between records.

If there is not a uniqueness conflict, that is, if the field-name-equals-value pair being stored is unique, <var class="product">Model 204</var> completes the update.

Note
If the UNIQUE attribute is not specified when a field is defined, the NON-UNIQUE attribute is assumed. 

Unique values in multiply occurring fields

In a multiply-occurring field, <var class="product">Model 204</var> ensures that each occurrence of the field is unique. 
Deleting UNIQUE fields

Because UNIQUE values use the Ordered Index, do not use the DELETE ALL RECORDS statement for deleting records. Use DELETE RECORD instead.
Compatibility with other attributes

A field can only be specified as UNIQUE with the following restrictions:
<ul>
<li>UNIQUE fields must be specified as ORDERED.</li>
<li>UNIQUE fields cannot be specified as DEFERRABLE.</li>
<li>UNIQUE fields cannot be defined in non-TBO (Transaction back out) files. </li>
</ul>

If you attempt to define a UNIQUE key under any of these circumstances, you receive an error message and the field is not defined.

===Content constraints===

====Setting a pattern for a field value: the LIKE attribute====
The LIKE attribute is available as of Model 204 release 7.5.

Setting a field pattern lets you specify a pattern that a field value must conform to, otherwise it cannot be stored. The patterns you can specify are the <var class="product">Model 204</var> <var>[[Is_Like_pattern_matching#Pattern_matching|LIKE]]</var> patterns.
For example:
IN FILE PITCHERS DEFINE FIELD G WITH LIKE '@@@####'


This example specifies that field G must start with three alphabetic characters followed by four numeric characters. An attempt to store a field value that does not conform to the field's pattern results in request cancellation.

You can limit a field value to a list of values. For, example, if a field must have a value of 'M' or 'F' you could code:
IN FILE PITCHERS DEFINE FIELD SEX WITH LIKE 'M,F'


And if you want a BALL field to have a value 'SPLITTER', 'CURVE', 'KNUCKLE', or 'CHANGE UP' you could code:
IN FILE PITCHERS DEFINE FIELD BALL WITH LIKE -
'SPLITTER,CURVE,KNUCKLE,CHANGE UP'


The maximum pattern length is 47 characters. The maximum default value length is 31 characters.

As with the IS LIKE operator in SOUL, the patterns are always applied to numbers after conversion to a string.

You cannot use the <var>LIKE</var> attribute to define an automatic field.

====Range constraints====
Range constraints are available as of Model 204 version 7.5.

You can set range constraints on fields using the range attributes. Each set of range attributes is comprised of three or four attributes that you can use to establish a range for field length values, integer values, float values, or date/time stamp values. The types of range attributes are mutually exclusive. For example, you cannot define a field with the LENGTH-GE and INTEGER-LE attributes. 

The range constraints are self-editing. If you define a field with LENGTH LE 6 and LENGTH GE 8, the definition is rejected and an error message is issued.

When a range constraint is redefined, it replaces the existing field constraint.
Note: The range constraints do not have to match the data type of the stored field. That is, you can have a date/time constraint for a STRING field or an integer constraint for a FLOAT field, and so on.

=====Defining fields with length constraints=====
<table>
<tr class="head">
<th>Length constraint attributes </th>
<th>
Range</th>
</tr>

<tr>
<td>LENGTH-EQ </td>
<td>Number from 0 to 255 that indicates the required length of a field</td>
</tr>

<tr>
<td>LENGTH-GE </td>
<td>Number from 0 to 255 that indicates the minimum length of a field</td>
</tr>

<tr>
<td>LENGTH-LE </td>
<td>Number from 0 to 255 that indicates the maximum length of a field</td>
</tr>
</table>

The following field definitions illustrate using the length constraint attributes, LENGTH-EQ, LENGTH-GE, and LENGTH-LE, with each other and/or with other attributes.
IN FILE REDSOX DEFINE FIELD A WITH LENGTH-EQ 8 BINARY OCCURS 1

IN FILE REDSOX DEFINE FIELD B WITH LENGTH-GE 4 FLOAT LEN 8

IN FILE REDSOX DEFINE FIELD C WITH LENGTH-LE 10

IN FILE REDSOX DEFINE FIELD D WITH LENGTH-LE 10 LENGTH-GE 3

IN FILE REDSOX DEFINE FIELD E WITH LENGTH-LE 6 LENGTH-GE 6 BINARY

IN FILE REDSOX DEFINE FIELD F WITH LENGTH-LE 255 LENGTH-GE 0

IN FILE REDSOX DEFINE FIELD COLOR WITH EXACTLY-ONE

Note: The length constraints apply to the string representation of non-string types as they would be stored in the database. This means that the length of a FLOAT field with value 34.000 would be 2 because after being stored in the database it will return 34 on a retrieval.

=====LENGTH-EQ (LEQ) attribute=====

The LENGTH-EQ attribute is followed by a number from 0 to 255 that indicates the required length of a field.

The LENGTH-EQ attribute is not allowed for automatic fields.

=====LENGTH-GE (LGE) attribute=====

The LENGTH-GE attribute is followed by a number from 0 to 255 that indicates the minimum length of a field.

The LENGTH-GE attribute is not allowed for automatic fields. You can pair the LGE attribute with the LLE attribute, creating a length range. However, if the range is not valid or overlaps, an error message is invoked.

=====LENGTH-LE (LLE) attribute=====

The LENGTH-LE attribute is followed by a number from 0 to 255 that indicates the maximum length of a field.

The LENGTH-LE attribute is not allowed for automatic fields. You can pair the LLE attribute with the LGE attribute, creating a length range. However, if the range is not valid or overlaps, an error message is invoked.

=====Setting an integer value constraint=====

For Integer values you can define a field with:
<table>
<tr class="head">
<th>Integer attribute </th>
<th>Specifies that the integer value must be...</th>
</tr>

<tr>
<td>INTEGER-GE </td>
<td>Greater than or equal to the value that follows</td>
</tr>

<tr>
<td>INTEGER-GT </td>
<td>Greater than the value that follows</td>
</tr>

<tr>
<td>INTEGER-LE </td>
<td>Less than or equal to the value that follows</td>
</tr>

<tr>
<td>INTEGER-LT</td>
<td>Less than the value that follows</td>
</tr>
</table>

The value stored for a field must be an integer with a value that satisfies the constraint. For example:
DEFINE FIELD NCHILDREN WITH INTEGER-LE 100


The NCHILDREN field can have an integer value of less than or equal to 100.
Note: An integer constraint will not accept a value that would be stored with a decimal place. If you have an integer constraint INTEGER-GE 10 and try to store value 10.0, it will fail because 10.0 is not an integer.

=====INTEGER-GE (INTGE), INTEGER-GT (INTGT), INTEGER-LE (INTLE) and INTEGER-LT (INTLT) attributes=====

The integer range attributes (INTGE, INTGT, INTLE, and INTLT) establish a range of acceptable integer values for a field. These attributes can be defined singly or as a pair on the field. The integer range attributes If a record is added with an integer value that is not within the range, the record is rejected.

If you specify another type of range attribute on the same field, such as DATETIME-LE or FLOAT-GE, an error message is invoked. 

=====Setting a float value constraint=====

For float values you can define a field with:
<table>
<tr class="head">
<th>Float attribute </th>
<th>Specifies that the float value must be...</th>
</tr>

<tr>
<td>FLOAT-GE </td>
<td>Greater than or equal to the value that follows</td>
</tr>

<tr>
<td>FLOAT-GT </td>
<td>Greater than the value that follows</td>
</tr>

<tr>
<td>FLOAT-LE </td>
<td>Less than or equal to the value that follows</td>
</tr>

<tr>
<td>FLOAT-LT</td>
<td>Less than the value that follows</td>
</tr>
</table>

The value stored for a field must be a floating point value that satisfies the constraint. For example:
DEFINE FIELD WEIGHT WITH FLOAT-GT 10.5


The WEIGHT field must have a float value greater than 10.5. 

=====FLOAT-GE (FLTGE), FLOAT-GT (FLTGT), FLOAT-LE (FLTLE) and FLOAT-LT (FLTLT) attributes=====

The float range attributes (FLTGE, FLTGT, FLTLE, and FLTLT) establish a range of acceptable float values for a field. These attributes can be defined singly or as a pair on the field. If a record is added with a float value that is not within the range, the record is rejected.

If you specify another type of range attribute on the same field, such as DATETIME-LE or INTEGER-GE, an error message is invoked. 

=====Setting a date/time value constraint=====

For date/time values you can define a field with:
<table>
<tr class="head">
<th>Date/time attribute </th>
<th>Specifies that the date/time value must be...</th>
</tr>

<tr>
<td>DATETIME-GE </td>
<td>Later than or the same as the date/time value that follows</td>
</tr>

<tr>
<td>DATETIME-GT </td>
<td>Later than the date/time value that follows</td>
</tr>

<tr>
<td>DATETIME-LE </td>
<td>Earlier or equal to the date/time value that follows</td>
</tr>

<tr>
<td>DATETIME-LT </td>
<td>Earlier than the value that follows</td>
</tr>
</table>

The value stored for field must be a date/time value that satisfies the constraint. For example:
DEFINE FIELD BIRTHDATE WITH DATETIME-GE 18900101 DATETIME-LT 20100101


The BIRTHDATE field is required to have a date/time value greater than or equal to January 1, 1890 and less than January 1, 2010. As with any other date/time values, the values can be extended with HH, HHMM, HHMMSS, HHMMSSX, HHMMSSXX, and so on.

=====DATETIME-GE (DTGE), DATETIME-GT (DTGT), DATETIME-LE (DTLE), and DATETIME-LT (DTLT) attributes=====

The date/time range attributes-DTGE, DTGT, DTLE, DTLT-establish a range of acceptable dates for the value of the field. If a record is added with a date that is not within the range, the record is rejected. You can specify a single date/time range attribute or a pair of them on a field. 

If you specify another type of range attribute on the same field, such as FLOAT-LE or INTEGER-GE, an error message is invoked. 

The value stored for a field must be a date/time with a value that has the proper relationship to the following value. For example:
DEFINE FIELD BIRTHDATE WITH DATETIME-GE 18900101 DATETIME-LT 20100101


The BIRTHDATE field is required to have a date/time value greater than or equal to January 1, 1890 and less than January 1, 2010. As with any other date/time values, the values can be extended with HH, HHMM, HHMMSS, HHMMSSX, HHMMSSXX, and so on.

==Concatenated fields==
Note: The concatenated fields feature is available as of Model 204 version 7.5.

Fields listed after <var>CONCATENATION OF</var>:
<ul>
<li>Must be either AT-MOST-ONE, EXACTLY-ONE, or OCCURS 1 (any mixture of these field types is allowed)
<li>Must all be in the same field group, or must all not be in any field group
<li>Cannot have the <var>FIELDGROUP *</var>, <var>BLOB</var>, nor <var>CLOB</var> attribute
<li>Cannot have any of the [[#Range constraints|range attributes]]
</ul>


The following syntax is used to define a concatenated field with a separator and an escape character:

Syntax
DEFINE FIELD fieldname WITH CONCATENATION-OF -
field1 WITH field2 [WITH field3 [WITH field4 -
[AND . . .]]] -
[SEPARATOR (char | X'hex' | NONE)] -
[ESCAPE (char | X'hex' | CANCEL)]
[OtherAttributes . . .]


The SEPARATOR character appears between the field values that comprise the concatenated field. Up to eight fields can be defined for a concatenated field. 

Concatenated fields could be longer than 255 bytes after adding separator and escape characters; in this case, the request is cancelled.

Concatenated fields have the following field attribute support.
<table>
<tr class="head">
<th>Concatenated field attributes </th>
<th>Purpose</th>
</tr>

<tr>
<td>CONCATENATION-OF (CAT) </td>
<td>List the fields that make up that concatenated field</td>
</tr>

<tr>
<td>ESCAPE (ESC) </td>
<td>Specifies a character that is used to escape separator characters that occur in a field that requires a terminating separator character</td>
</tr>

<tr>
<td>SEPARATOR (SEP) </td>
<td>Specifies the character that terminates fields that do not have a fixed length and are not the last field in the concatenation</td>
</tr>
</table>

If a required attribute is not assigned a value, the default value is used. For example, if you define a CONCATENATION-OF field, which requires the SEPARATOR attribute, and you do not enter the SEPARATOR attribute, the default value of X'00' is used as the SEPARATOR value.
See the "Record retrievals" topic for more information on record retrieval of concatenated fields, including the use of [[Record_retrievals#EQ_WITH_retrieval_condition_for_concatenated_fields|EQ WITH]].

===CONCATENATION-OF (CAT) attribute===

The CONCATENATION-OF (CAT) attribute is followed by a list of fields that make up that concatenated field. At least two are required and up to eight are allowed. The field names must be separated by the word WITH and subsequent field attributes must be separated from the list by the word <var>AND</var> or by a comma. Each field specified in the list of concatenated fields must have the <var>EXACTLY-ONE</var>, <var>AT-MOST-ONE</var>, or <var>OCCURS 1</var> attribute specified.
If a field to be concatenated is an <var>OCCURS 1</var> field, define its LENGTH attribute as the total of the longest possible concatenation (including separators) to avoid a "too long" result.

If LENGTH is less than 255, a "too long" result produces message M204.0738.
If LENGTH is 255, a "too long" result produces M204.2872, which cancels the request.

===ESCAPE (ESC) attribute===

The ESC attribute is followed by one of the following:
<ul>
<li>A single character in C'<var class="term">char</var>' or X'<var class="term">hex</var>' format that specifies the character used to escape separator characters that occur in a field requiring a terminating separator character. In addition to escaping the separator character, the escape character can also escape itself.</li>

<li>CANCEL, which means that an attempt to store a separator character in a field that requires a terminating separator results in request cancellation.</li>
</ul>

The default ESCAPE character is X'01'. 

Once you define an ESCAPE value for a field, you cannot redefine the ESCAPE value.

The ESCAPE character cannot match the SEPARATOR character. The ESCAPE character is always displayed on DISPLAY FIELD output.

The ESCAPE attribute is not allowed on a field definition, if the SEPARATOR NONE attribute is specified.

Using the ESCAPE attribute

The ESC character is inserted into a concatenated field when the real data being added to the database contains the SEPARATOR or the ESCAPE character itself. When reading in stored values, programs use the ESC character to differentiate between those special characters and normal data that happens to include those special characters. When the processing encounters the ESCAPE character in a concatenated field, it knows that the next character is real data.
Note: The ESCAPE character applies to all fields except the last field in the concatenation. The programmer is expected to know how many components comprise the concatenation and therefore, special characters occurring in the last component must be real data.

Consider the following field definitions:
DEFINE FIELD A_CONCAT_TEST1 WITH AT-MOST-ONE
DEFINE FIELD A_CONCAT_TEST2 WITH AT-MOST-ONE
DEFINE FIELD A_CONCAT_TEST3 WITH CONCATENATION-OF -
A_CONCAT_TEST1 WITH -
A_CONCAT_TEST2 AND -
SEPARATOR C'+' -
ESCAPE C'/'


If we then do:
BEGIN
IN POLICIES STORE RECORD
A_CONCAT_TEST1 = 1ST+VALUE+
A_CONCAT_TEST2 = 2ND+VALUE+
END STORE
FRN $CURREC
NP
PAI
END FOR
END


We get:
A_CONCAT_TEST1 = 1ST+VALUE+
A_CONCAT_TEST2 = 2ND+VALUE+
A_CONCAT_TEST3 = 1ST/+VALUE/++2ND+VALUE+


The plus signs in the stored records are intentionally part of the data. For the concatenated field <var class="product">Model 204</var> stores the escape character preceding the plus signs in the data for all but the last field in the concatenation. This assumes that the programmer knows how many fields there are in the concatenation and therefore knows that any separator characters in the last field are data fields.

In storing the escape character immediately before any plus signs that are part of the data proper, <var class="product">Model 204</var> tells the programmer that they are to be read as data. If there were any escape characters in the data proper, <var class="product">Model 204</var> puts an escape character before the data proper version as in the following example:
BEGIN
IN POLICIES STORE RECORD
A_CONCAT_TEST1 = 1ST/VALUE+
A_CONCAT_TEST2 = 2ND+VALUE+
END STORE
FRN $CURREC
NP
PAI
END FOR
END


This is the output:
A_CONCAT_TEST1 = 1ST/VALUE+
A_CONCAT_TEST2 = 2ND+VALUE+
A_CONCAT_TEST3 = 1ST//VALUE/++2ND+VALUE+


If you do not want either the separator or the escape character in the concatenated field, you can enforce this by assigning the value <code>CANCEL</code> as the escape character as follows:
DEFINE FIELD A_CONCAT_TEST1 WITH CONCATENATION-OF -
A_CONCAT_TEST1 WITH -
A_CONCAT_TEST2 AND -
SEPARATOR C'+' -
ESCAPE CANCEL


In which case, the concatenation will be ignored and our STORE record results in the following:
A_CONCAT_TEST1 = 1ST/VALUE+
A_CONCAT_TEST2 = 2ND+VALUE+

Note: There are no error messages associated with this condition.

If you specify the ESCAPE CANCEL attribute for a field and the SEPARATOR character for that field is in one of the field values for the concatenated string, the update is cancelled. For an example, see [[Record_retrievals#Limitations_when_using_ESCAPE_CANCEL|Limitations when using ESCAPE CANCEL]].

===SEPARATOR (SEP) attribute===

The SEP attribute is followed by one of the following options:
<ul>
<li>A single character in C'<var class="term">char</var>' or an X'<var class="term">hex</var>' format that specifies the character that terminates fields that do not have a fixed length and are not the last field in the concatenation. The separator character is always used between field values, regardless of any length constraints on the component fields.</li>

<li>The NONE option that means the fields in the concatenation are concatenated end to end with no separator character and regardless of their length.</li>
</ul>

If you define a field with the SEP attribute, you must supply a value. Otherwise, the following error is issued:
DEFINE MAKE_MODEL WITH CONCATENATION-OF MAKE WITH MODEL - AND ORD SEP ESC CANCEL
*** 1 M204.0405: INVALID DEFINE OPTION: SEP ESC


If you define a field without the SEP attribute, it defaults to X:00:, as shown in the following code:
DEFINE MAKE_MODEL WITH CONCATENATION-OF MAKE WITH MODEL -
AND ORD ESC CANCEL

D FIELD (ABBREV) MAKE_MODEL
MAKE_MODEL
(DEF NFRV NKEY NCOD STR NNR VIS UP ORD CHAR LRES 15 -
NRES 15 SPLT 50 IMM 1 NUNIQ ONE CAT MAKE WITH MODEL AND -
SEP X'00' EXC CANCEL)


Once you define a SEPARATOR value for a field, you cannot redefine the SEPARATOR value.

The SEPARATOR character cannot match the ESCAPE character. The SEPARATOR character is always displayed on DISPLAY FIELD output.

If the SEPARATOR NONE attribute is specified on a field definition, the ESCAPE attribute is not allowed.See the Record retrievals topic for notes on [[Record_retrievals#Limitations_when_using_SEPARATOR_NONE|limitations when using SEPARATOR NONE]].

===Defining concatenated fields===

Using the fields defined in [[|]] and the following fields, you can define concatenated fields.
IN FILE REDSOX DEFINE FIELD COLMOD WITH CONCATENATION-OF COLOR -
WITH MODEL AND SEP C'-' ESC C'+'

IN FILE REDSOX DEFINE FIELD MODCOL WITH CONCATENATION-OF MODEL -
WITH COLOR AND SEP C'$' ESC C'*'

IN FILE REDSOX DEFINE FIELD MODCOLI WITH CONCATENATION-OF MODEL -
WITH COLOR AND SEP X'40' ESC C'*' INVISIBLE ORDERED

IN FILE REDSOX DEFINE FIELD MCY WITH CONCATENATION-OF MODEL -
WITH COLOR WITH YEAR AND SEP X'40' ESC C'*' INVISIBLE ORDERED

IN FILE REDSOX DEFINE FIELD COLCNT WITH CONCATENATION-OF COLOR -
WITH COUNTRY AND SEP X'40' ESC C'*' INVISIBLE ORDERED

IN FILE REDSOX DEFINE FIELD CNTYR WITH CONCATENATION-OF YEAR -
WITH COUNTRY AND SEP X'40' ESC C'*' INVISIBLE ORDERED


===Defining concatenated fields in a field group context===
IN FILE REDSOX DEFINE FIELD BATTERS

IN FILE REDSOX DEFINE FIELDGROUP STARTERS

IN FILE REDSOX DEFINE FIELD NTRIP WITH CTO STARTERS AND EXACTLY-ONE

IN FILE REDSOX DEFINE FIELD A WITH AT-MOST-ONE FIELDGROUP STARTERS AND-
ORDERED CHARACTER

IN FILE REDSOX DEFINE FIELD B WITH AT-MOST-ONE FIELDGROUP STARTERS AND -
KEY

IN FILE REDSOX DEFINE FIELD C WITH AT-MOST-ONE FIELDGROUP STARTERS AND
ORDERED NUMERIC

IN FILE REDSOX DEFINE FIELD AB WITH FIELDGROUP STARTERS AND -
CONCATENATION-OF A WITH B AND SEP C'/'

IN FILE REDSOX DEFINE FIELD ABO WITH FIELDGROUP STARTERS AND -
CONCATENATION-OF B WITH A AND SEP C'+' ORDERED

IN FILE REDSOX DEFINE FIELD ABI WITH CONCATENATION-OF B WITH A AND -
SEP C'+' ORDERED INVISIBLE

Note: A field in a concatenated field value does not have a terminating separator set only if it is:
<ul>
<li>Last field in the concatenation, or</li>
<li>Fixed length (LENGTH-EQ set) and the default value has the same length as LENGTH-EQ.</li>
</ul>

<div id="Automatic Fields">

==Automatic fields==
Note: Automatic fields are available as of Model 204 version 7.5 and require the <var>[[FILEORG_parameter|FILEORG]]</var> X'100' setting.

<var class="product">Model 204</var> lets you define a field whose value is automatically maintained. For example, a field might count occurrences of another field so that every store or delete of the field occurrence changes the count in the automatic field. An automatic field is defined with one of the following attributes: 
<ul>
<li>CHUNK</li>
<li>COUNT-OCCURRENCES-OF</li>
<li>CREATE-TIME</li>
<li>CREATE-TIMEUTC</li>
<li>CREATE-USER</li>
<li>UPDATE-TIME</li>
<li>UPDATE-TIMEUTC</li>
<li>UPDATE-USER</li>
</ul>

The value of an automatic field is updated at the start of a transaction by <var class="product">Model 204</var> and you cannot set it explicitly by a program. Any valid update causes the appropriate time and user stamps to be updated. For example, DELETE FOO(8). when there are no occurrences of FOO in the record.

Once you define an automatic value for a field, you cannot redefine the automatic value.

User Language ADD, INSERT, DELETE, and STORE RECORD statements will be rejected with a compile error if they reference an automatic field:

M204.2862: ATTEMPT TO UPDATE AUTOMATIC FIELD fieldname


If a field name variable (FNV) used on an update UL statement resolves to an automatic field,
the request will be cancelled with the following error:

M204.2863: ATTEMPT TO DO updateOperation FOR AUTOMATIC FIELD: fieldname

On an update statement in group context, the M204.2863 error will also be issued if the field being updated is discovered to be an automatic field in one of the group's files at evaluation time.

===Automatic field context===

Automatic fields can operate in a record or field group context. For example, with the following set of fields:

...
DEFINE FIELDGROUP ADDRESS
...
DEFINE FIELD RECORD.UPDT.TIME (DATETIME UPDT-TIME)
DEFINE FIELD ADDRESS.LINE.1 (SN NONE FG ADDRESS)
...
DEFINE FIELD ADDRESS.UPDT.TIME (DATETIME FG ADDRESS AND UPDT-TIME)
...
<ul>
<li>Any update to any field in a record will automatically update RECORD.UPDT.TIME.</li>

<li>Any update to any field in an occurrence of the ADDRESS field group will cause the ADDRESS.UPDT.TIME for that occurrence to be updated. (And, of course, the record level RECORD.UPDT.TIME as well.) </li>
</ul>

===Rules for the definition of automatic fields===

'''CHUNK attribute'''

Fields defined with the CHUNK field attribute cannot be redefined or deleted.

'''COUNT-OCCURRENCES-OF (CTO) attribute'''

The COUNT-OCCURRENCES-OF (CTO) attribute is not allowed for fields defined as REPEATABLE.

Because one of the major advantages of CTO fields is to avoid unnecessary record scans, it is highly recommended that the field be preallocated. Otherwise the field is stored and updated in Table B in the normal way.

See [[#cto|CTO fields]] for details on its use.

'''CREATE* and UPDATE* attributes'''

The CREATE-TIME, CREATE-TIMEUTC, CREATE-USER, UPDATE-TIME, UPDATE-TIMEUTC, and UPDATE-USER automatic fields capture the add/update user/time as of the start of the transaction. Any of these attributes can be added to empty or non-empty fields (using a <var>REDEFINE</var> command). The value is maintained by <var class="product">Model 204</var> processing, so you cannot change the value.

These automatic attributes cannot be defined as REPEATABLE (the default is AT-MOST-ONE).

See [[#Tracking updates using automatic fields|Tracking updates using automatic fields]] for details on their use.

===Displaying automatic fields===

You can specify the AT-MOST-ONE or EXACTLY-ONE attribute for an automatic field. These attributes affect the order in which the fields are displayed on a PAI statement. EXACTLY-ONE fields are displayed in the order they were defined, whereas AT-MOST-ONE fields are displayed in the order they are stored in Table B. 

Currently Table B stores the following automatic fields in the order shown:
<ol>
<li>UPDATE-TIME</li>
<li>UPDATE-USER</li>
<li>CREATE-TIME</li>
<li>CREATE-USER</li>
</ol>

<div id="cto"></div>

<div id="Counting occurrences of a field"></div>
===CTO fields: counting occurrences of a field===



To create an automatic count field you use the COUNT-OCCURRENCES-OF (CTO) keyword on a field definition, followed by the name of the field or field group for which the count is automatically maintained. For example, if you have field group DRUG you could define an automatic count field as follows:
DEFINE FIELDGROUP DRUG
DEFINE FIELD DRUGCT WITH COUNT-OCCURRENCES-OF DRUG


You cannot define a CTO field in a file that has had records already added to it.

You could also make the automatic count field a binary field:
DEFINE FIELD DRUGCT WITH CTO DRUG AND BINARY OCCURS 1
DEFINE FIELD DRUGCT WITH COUNT-OCCURRENCES-OF DRUG AND -
BINARY

Note: AND is a separator between a field or field group name and other field attributes.

An automatic count field can also be an OCCURS 1 field:
DEFINE FIELD DRUGCT WITH COUNT-OCCURRENCES-OF DRUG AND BINARY OCCURS 1


An automatic count field could even be ORDERED, KEY or NUMERIC RANGE:
DEFINE FIELD DRUGCT WITH CTO DRUG AND BINARY OCCURS 1 ORDERED NUMERIC


You can find all records with N occurrences of field group DRUG. Or, you can find those that have more or less than some number of occurrences.
Limitations on COUNT-OCCURRENCES-OF (CTO) fields

Fields defined with the CTO attribute cannot also have the UPDATE AT END attribute. You cannot define a CTO field that counts occurrences of UPDATE AT END fields.

You cannot use a CTO field to count occurrences of OCCURS fields, even though the OCCURS count is greater than 1.

Also, you cannot define a CTO field in a file that has had records already added to it.

There is a maximum of one CTO field per field or field group.
Retrieving the value of a CTO field

You can retrieve values of CTO fields via the field name (as with any VISIBLE field), as in:
PRINT DRUGCT


or
%DRUGCT = DRUGCT

Automatic optimization with COUNT OCCURRENCES OF fields

The use of CTO fields automatically optimizes many of the record scan processes:
<ul>
<li>[[Processing multiply occurring fields and field groups#FOR EACH OCCURRENCE OF loops|FOR EACH OCCURRENCE OF]] loops.

If a CTO field exists for the field or field group that is being looped over via an FEO or FAO statement, the value of that field limits the number of times the loop is processed, which reduces the need to scan to the end of record for every FEO or FAO statement. Note that when a record is updated or might be updated mid-loop, <var class="product">Model 204</var> normal concerns about subscript handling in these statements need to be considered.
</li>

<li>FOR FIELDGROUP clause

Before processing a FOR FIELDGROUP loop, <var class="product">Model 204</var> checks whether the requested occurrence is in the record based on the CTO field. If the User Language request is for occurrence 3, but the CTO field indicates only two occurrences in the record, <var class="product">Model 204</var> stops processing the FOR loop.
</li>

<li>Field extraction

Before extracting a field <var class="product">Model 204</var> checks whether the requested occurrence is in the record based on the CTO field. If the User Language request is occurrence 3, but the CTO field indicates only two occurrences in the record, <var class="product">Model 204</var> sets the result to null (or NOT PRESENT). 

Note that in the case of the subscripted field optimization:

FOR %I FROM 1 TO %N
%FOO = FOOFIELD(%N)
END FOR


<var class="product">Model 204</var> checks only the number of occurrences on the first iteration of the loop.</li>
</ul>


In all cases, the greatest benefit from the CTO field optimization is when a record contains no occurrences of the requested field or field group. <var class="product">Model 204</var> immediately determines that no occurrence is on the record and stops scanning the record.

Defining an efficient CTO field

The counter fields are always physically present in the record. Using a DEFAULT-VALUE of zero for such a field defeats its purpose as you need to scan the entire record to determine whether to use the default value. When you issue a STORE RECORD statement, all CTO fields are stored as 0 in the record. For non-OCCURS, fields are always the first variable length fields in the record.

<var class="product">Model 204</var> customer support recommends that you define a CTO field as BINARY OCCURS 1, as these require only four bytes per record, whereas the minimum length of a variable length field is four bytes (for a compressed 0) and will be at least five for any non-zero value. A CTO field inside a field group cannot be an OCCURS field. 

The absolute maximum value for CTO fields is currently X'3FFFFFFF' or 1,073,741,823 since BINARY fields use the high order two bits to distinguish values from coded values. 

You cannot update CTO fields; attempts are caught at compile-time for explicit file-context references and at run-time for group-context and field-name variables. 

CTO fields can even be in field groups and zeros are stored for CTO fields when the ADD FIELDGROUP or INSERT FIELDGROUP statement is processed.
Displaying CTO fields

By default, the PRINT ALL INFORMATION (PAI), AUDIT ALL INFORMATION (AAI), PRINT ALL FIELD GROUP INFORMATION (PAFGI), and AUDIT ALL FIELDGROUP INFORMATION (AAFGI) statements do not display CTO (counter fields). When you are using PAI [INTO] to reorganize your files or to copy records, the automatic fields are likely to cause problems.

Under other circumstances you can use the argument to indicate that you do want automatic fields to be printed by these statements.

===Tracking updates using automatic fields===

Versions 7.5 and higher of <var class="product">Model 204</var> can track the date/time when a record was created or updated, and what user ID created or updated it.
This tracking can be accomplished by using one of the following field tracking attributes: 
<table>
<tr class="head">
<th>Tracking attribute </th>
<th>Abbreviation</th>
<th>Tracks the...</th>
</tr>

<tr>
<td>CREATE-TIME </td>
<td>CRTM</td>
<td>Moment the record was created using machine time</td>
</tr>

<tr>
<td>CREATE-TIMEUTC </td>
<td>CRTMU</td>
<td>Moment the record was created using Coordinated Universal Time</td>
</tr>

<tr>
<td>CREATE-USER </td>
<td>CRUS</td>
<td>User ID that created the record</td>
</tr>

<tr>
<td>UPDATE-TIME </td>
<td>UPTM</td>
<td>Moment the record was updated using machine time</td>
</tr>

<tr>
<td>UPDATE-TIMEUTC </td>
<td>UPTMU</td>
<td>Moment the record was updated using Coordinated Universal Time</td>
</tr>

<tr>
<td>UPDATE-USER </td>
<td>UPUS</td>
<td>User ID that updated the record</td>
</tr>
</table>

All of the automatic fields that contain date/time information also have the DATETIME attribute. 

You cannot update tracking fields with User Language.

A record or field group can contain only a single field of each update tracing type (CREATE-USER, UPDATE-USER, CREATE-TIME, UPDATE-TIME). An attempt to create a second invokes an error message.

You can define update tracking fields (CREATE-TIME, UPDATE-TIME, CREATE-USER, UPDATE-USER) in an already populated file, even an update tracking field for the main records or a field group that already has occurrences. You can also define a DEFAULT-VALUE field, which defaults to a null string. This lets you define such fields with or without a reorganization.
Tracking fields for records

The file itself can have a single field defined for each of the tracking fields.

An attempt to define a second field of the same type on the file results in an error message, for example:
DEFINE FIELD RECORD.CREATE.TIME WITH CREATE-TIME
DEFINE FIELD RECORD.CREATE-TIME2 WITH CREATE-TIME

*** M204.2866: FILE ALREADY HAS A CREATE-TIME FIELD


The <var>UPDATE</var> tracking fields for the records are updated when any field in the record changes and the create tracking fields are added to the record when it is initially stored. 

Tracking fields for field groups

Automatic tracking fields can also provide a date/time and user stamp of the creator and last update of each occurrence of a field group.

If an <var>UPDATE-TIME</var> tracking field is defined as a part of field group <code>X</code> as shown below, then each occurrence of that field group will contain the tracking field:
DEFINE FIELD MY_UPDATE_TIME WITH FIELDGROUP X AND ORD NUM UPDATE-TIME


Setting a date/time field

The <var>DATETIME</var> field attribute indicates the format of the data stored in Table B.

Once you define a field as <var>DATETIME</var>, you assign a string to it in <code>YYYYMMDDHHMMSSXXXXXX</code> format:
IN FILE FOO DEFINE FIELD WHEN WITH DATETIME
...
BEGIN
IN FILE FOO STORE RECORD
WHEN = '2010070413470643516378'
END STORE
END


If you attempt to store the field with invalid data such as, <code>WHEN = '72'</code>, the request is cancelled and you receive an error:
*** 1 CANCELLING REQUEST: M204.2865: ATTEMPT TO ADD INVALID DATETIME VALUE: WHEN = 72


As most timestamps do not require microseconds, you can specify 10ths, 100ths, 1,000ths, 10,000ths and 100,000ths of a second. The value is simply padded on the right with zeros. For date/time field <code>WHEN</code>, the following are all equivalent:
ADD WHEN = '20090704134706000000'
ADD WHEN = '2009070413470600000'
ADD WHEN = '200907041347060000'
ADD WHEN = '20090704134706000'
ADD WHEN = '2009070413470600'
ADD WHEN = '200907041347060'
ADD WHEN = '20090704134706'


In addition, you can leave off seconds, minutes or hours so the following are all equivalent:
ADD WHEN = '20090704000000'
ADD WHEN = '200907040000'
ADD WHEN = '2009070400'
ADD WHEN = '20090704'


which are also, of course, equivalent to
ADD WHEN = '20090704000000000000'


Storing dates or date/times efficiently

<var>DATETIME</var> fields use seven bytes to store their value (plus four bytes overhead, if the field is not preallocated). A binary representation is used to store the 20-character full date format so that it can be held in seven bytes. 

The shortest valid format for a field with the <var>DATETIME</var> attribute is <code>YYYYMMDD</code>. If the values you are storing are simple dates, they can be stored in four bytes as binary values, three fewer bytes per value than a date/time field. However, for anything with a time in it (even just hours), a <var>DATETIME</var> field takes less space than the alternative field types (<var>FLOAT</var> or <var>STRING</var>).

Automatic validation of date/times

In addition to the compact storage of date/time stamps, <var>DATETIME</var> fields also provide automatic validation of the values you attempt to stored in them — you cannot store numbers into them that are not valid dates. For example, you cannot store <code>'9999111'</code> into a <var>DATETIME</var> field, nor can you store <code>'20070931'</code> (because September does not have 31 days), nor can you store <code>'20070229'</code> (because 2007 is not a leap year, so February only has 28 days).

Additional <var>DATETIME</var>-formatted fields also provide for [[Field design#Setting a date/time value constraint|field content validation]] for date/time fields. 

Note: It is possible to set a <var>DEFAULT-VALUE</var> for a <var>DATETIME</var> field to an invalid date/time value, such as a hyphen <code>_</code>. That value will not be stored in the database, but it would be the value returned for a reference to a missing <var>EXACTLY-ONE</var> <var>DATETIME</var> field value.

The value returned for <var>DATETIME</var> fields is always in this format:
YYYYMMDDHHMMSSXXXXXX


If you are interested in only part of the time stamp, you can use either of these: 
<ul>
<li>The <var>$Substr</var> function to get the part you want. </li>

<li>A %variable specified to be the length of the part of the time stamp you are interested in. 
So, to use <code>%when</code> to hold a date/time in <code>YYYYMMDDHHMISS</code> format: 
%when is string len 14
...
%when= WHEN
</li>
</ul>

<var>DATETIME</var> values can be indexed either as <var>ORDERED CHARACTER</var> or <var>ORDERED NUMERIC</var>. If indexed as <var>ORDERED NUMERIC</var>, only the first 15 digits (<code>YYYYMMDDHHMISSX</code>) are indexed. If <var>ORDERED CHARACTER</var>, it is indexed as the string representation of the date/time value in the full <code>YYYYMMDDHHMISSXXXXXX</code> format.
Note: Making <var>DATETIME</var> fields <var>KEY</var> fields is not allowed.

Update processing

Date/time values are the date/time of the start of the update processing, so all records, fields and field groups updated by a single update get the same time stamp. Furthermore, the code that starts an update unit ensures that the date/time stamp of each update unit is unique.

The M204.0173 and M204.0172 messages were expanded to include the date/time stamp.
M204.0173: START OF UPDATE 12 AT 10:11:00.51 (20090705101100511734)


and
M204.0172: END OF UPDATE 12 AT 10:11:00.56 (20090705101100511734)


Defining various UPDATE-USER fields

To indicate whether an update tracking field applies to a record or field group, specify or do not specify the containing field group on the field definition. For example:
DEFINE FIELD WHO WITH UPDATE-USER


The WHO field contains the user ID of the last user that updated anything in the record. The following example illustrates defining an UPDATE-USER field in a field group:
DEFINE FIELD DR.WHO WITH UPDATE-USER FIELDGROUP DR


The DR.WHO field contains the user ID of the last user that updated an occurrence of field group DR.

Defining various UPDATE-TIME fields

You can specify an update tracking field as FIELDGROUP *, which means that all field groups and the primary record all use the same update tracking field. For example:
DEFINE FIELD WHEN WITH UPDATE-TIME FIELDGROUP *


The WHEN field is placed in the primary record and each field group to track the last update time. If a file has a FIELDGROUP * update tracking field and a field group or record has a different comparable updating tracking field, the field group or the record specific tracking field applies to the field. For example:
DEFINE FIELD WHEN WITH UPDATE-TIME FIELDGROUP *

DEFINE FIELD MAIN.WHEN WITH UPDATE-TIME OCCURS 1

DEFINE FIELD FOO.WHEN WITH UPDATE-TIME FIELDGROUP FOO

<ul>
<li>The field WHEN would be updated for changes to any field group occurrences in field groups that do not have their own UPDATE-TIME field defined.</li>

<li>The Field MAIN.WHEN would be set for any update to any field in the record.</li>

<li>The field FOO.WHEN would be set in field group FOO for any update to a field group occurrence.</li>
</ul>

The UPDATE-TIME field in a field group that has a nested field group will be updated when the nested field group is updated, even though no fields in the containing field group were updated.

===An alternate approach to adding a date-time stamp field to your files===

There is a more general way you can include a date-time stamp field in your files. The date-time stamp feature lets you put a date-time stamp (DTS) on each record that was updated in a transaction. You can then use the data in the <var class="term">date-time stamp</var> field in an end-user written application to find and process all the rows of data that were changed.

An application that processes these records can track the <var class="term">date-time stamp</var> field values that have been processed to date, or it might take another action, including updating the date-time stamp field.

To install and use this functionality, see [[Setting up the date-time stamp field]]. Once installed, the date-time stamp feature works only in files created in V6R1.0 or later. See [[Adding a date-time stamp field]]

Note: There is no support in PQO/204 for the date-time stamp feature.

====Difference between the system wide date-time stamp field and an UPDATE-TIME field====

Besides the obvious difference that the date-time stamp field will (and must) have the same name in every file in which it is used, the following are the notable differences between the two approaches:
<ul>
<li>The UPDATE-TIME attribute can be set to track updates to physical field groups, as well as at the record level.

<li>The UPDATE-TIME captures the time at the start of an update unit, the date-time stamp field captures the time at the commit point.

<li>The date-time stamp field updates can be [[Adding a date-time stamp field#Suspending date-time stamp updates|temporarily suspended]].
</ul>

== Assigning fields to field groups ==

===FIELDGROUP attribute===

No default, can be abbreviated as <var>FG</var>. <var>FIELDGROUP</var> is available as of Model 204 version 7.5.

The <var>FIELDGROUP</var> attribute specifies the name of the field group that the
defined field is associated with (contained in). Once you define a <var>FIELDGROUP</var>
value for a field, you cannot redefine the <var>FIELDGROUP</var> value.

The <var>FIELDGROUP</var> attribute cannot refer to a field group name that has not yet been defined to the file. The <var>[[DEFINE FIELDGROUP command|DEFINE FIELDGROUP]]</var> command must occur before the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command.

===Syntax===
FIELDGROUP [fieldgroupname | *]


The <var>FIELDGROUP</var> attribute does not allow:
<ul>
<li>Record security
<li>Use for <var>SORT</var> or <var>HASH</var> file
<li>1NF file model
</ul>

The <var>FIELDGROUP</var> attribute can be used with the <var>STORE-NULL LITERAL</var>
attribute.

===Using FIELDGROUP * ===

The <var>FIELDGROUP *</var> attribute means that the field will be included into all
field groups. The <var>EXACTLY-ONE</var> attribute conflicts with the <var>FIELDGROUP *</var> attribute.

<div id="Defining a LEVEL clause"></div>
<div id="LEVEL attribute"></div>
==LEVEL attribute - prevent unauthorized field usage==
To secure a field against unauthorized access, include a LEVEL clause in the field's description. [[Security#Field-level security|Field-level security]] discusses field-level security and describes the types of field access: SELECT, READ, UPDATE, and ADD.

Field-level security has a negligible impact on both performance and storage usage.

==Field naming==
The rules for field and field group naming are contained in [[Field names]].

[[Category:Model 204 files]]

New and updated messages in Model 204 version 7.5

2015-07-30T23:18:40Z

Tbullock: Was missing the "File"

[[Release_notes_for_Model_204_version_7.5|Back to 7.5 Release Notes]]

<div class="noautonum">__TOC__</div>

==M204 messages==
===Mixed case messages by default===
As of version 7.5, all Model 204 messages are issued with mixed case text by default unless [[UPCASMSG parameter|UPCASMSG]] is set.
===M204.0141: Bug .. duplicate file name in cp record===
Explanation: A duplicate file name was encountered while attempting to add a deferred update dataset to the file directory during recovery. This indicates a potential problem in the Model 204 software.

System Manager Response: Contact Technical Support with the following documentation:
<ul>
<li>Audit trail from the previous run</li>
<li>Journal from the previous run</li>
</ul>
Return Codes: E 0 4 AD OPR

----

===M204.0204: Parameter <var class="term">parmName</var> obsolete and not reset===
'''Explanation:''' Writing records to the SMF data set no longer requires the installation of an SVC. The
SMFSVC parameter is therefore obsolete and cannot be reset.
 '''System Manager Response:''' No response required.
 '''Return Codes:''' I 0 0 AUDITMS

----

===M204.0316: Recursive ON units exceed MAXOND: Evaluation stopped===
'''Explanation:''' During evaluation, one or more ON units was entered recursively. When the number of recursions exceeded MAXOND, the evaluation was terminated.
 '''System Manager Response:''' This message might indicate a logic error in the program. Inform the program author.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.0332 and M204.0336===
These messages indicate problems with the CRAM interface.
The visibility of these messages has been improved by:
<ul>
<li>writing the message to the operator and the JESLOG
<li>writing the message as an ER line in CCAAUDIT
<li>setting the return code to 80
</ul>

====M204.0332: RC ''nn'' from CRFS OPEN====
'''Explanation:''' The run has failed to initialize due to problems with the CRAM interface.
The possible formats of this message are:

Format 1: RC nn from CRFS OPEN/PUT/GET

Format 2: ECB postcode from CRFS PUT/GET
<ul>
<li>
Format 1 indicates that Model 204 module CRFS attempted to open channel, send a message down the channel, or receive a message from a channel. CRAM was unable to satisfy the request. The message states the return code and the
operation attempted.</li>
<li>
Format 2 indicates that Model 204 module CRFS received an unexpected post code from CRAM while attempting an I/O operation on a channel. The message states the post code and the operation attempted.
</li>
</ul>
Possible return codes include the following values:
<table>
<tr class="head"><th>Value</th> <th>Description</th>
<tr><td>4</td> <td>INVALID FUNCTION</td></tr>
<tr><td>8</td> <td>CB FORMAT ERROR</td></tr>
<tr><td>16</td> <td>(OPEN MAST) CHANNEL ALREADY OPEN</td></tr>
<tr><td>20</td> <td>(OPEN USER) NO USER LINES FREE</td></tr>
<tr><td>24</td> <td>(OPEN) SUBTASKS NOT PROPERLY OPENED</td></tr>
<tr><td>12</td> <td>(READ/WRITE) ICB NOT OPEN</td></tr>
<tr><td>16</td> <td>(READ/WRITE) OTHER TASK HAS DIED</td></tr>
<tr><td>20</td> <td>(READ/WRITE) UNEXPECTED COMMAND</td></tr>
<tr><td>28</td> <td>NOT ENOUGH STORAGE</td></tr>
<tr><td>99</td> <td>There is no SVC defined in the IGCLM244 module and the XMEMOPT ’80’ bit must be set for an SVC-less installation</td></tr>
<tr><td>110</td> <td>(VMCF WRITE) MESSAGE LIMIT EXCEEDED</td></tr>
</table>
'''System Manager Response:''' Contact Technical Support and have the audit trail available.
 '''Return Codes:''' C 80 80 AUDITER NOTERM OPR

====M204.0336: RC ''nn'' from CRIO OPEN====
'''Explanation:''' The run has failed to initialize due to problems with the CRAM interface.
The possible formats of this message are:

Format 1: RC nn from CRIO OPEN/PUT/GET

Format 2: ECB postcode from CRFS PUT/GET
<ul>
<li>
Format 1 indicates that Model 204 module CRIO attempted to open a channel,
send a message down a channel, or receive a message from a channel. CRAM
was unable to satisfy the request. The message states the return code and the
operation attempted. For example, the return code 16 indicates that the CRAM
channel is already open.</li>
<li>
Format 2 indicates that a Model 204 CRAM interface module, such as CRFS or CRIO, received an unexpected post
code from CRAM while attempting an I/O operation on a channel. The message
shows the post code and the operation attempted.</li>
</ul>
Possible return codes include the following values:
<table>
<tr class="head"><th>Value</th> <th>Description</th>
<tr><td>4</td> <td>INVALID FUNCTION</td></tr>
<tr><td>8</td> <td>CB FORMAT ERROR</td></tr>
<tr><td>16</td> <td>(OPEN MAST) CHANNEL ALREADY OPEN</td></tr>
<tr><td>20</td> <td>(OPEN USER) NO USER LINES FREE</td></tr>
<tr><td>24</td> <td>(OPEN) SUBTASKS NOT PROPERLY OPENED</td></tr>
<tr><td>12</td> <td>(READ/WRITE) ICB NOT OPEN</td></tr>
<tr><td>16</td> <td>(READ/WRITE) OTHER TASK HAS DIED</td></tr>
<tr><td>20</td> <td>(READ/WRITE) UNEXPECTED COMMAND</td></tr>
<tr><td>28</td> <td>NOT ENOUGH STORAGE</td></tr>
<tr><td>99</td> <td>There is no SVC defined in the IGCLM244 module and the XMEMOPT ’80’ bit must be set for an SVC-less installation</td></tr>
<tr><td>110</td> <td>(VMCF WRITE) MESSAGE LIMIT EXCEEDED</td></tr>
</table>
'''System Manager Response:''' Contact Technical Support and have the audit trail available.
 
'''Return Codes:''' C 80 80 AUDITER NOTERM OPR

----

===M204.0349: Login failed (<var class="term">alternative text</var>) Enter logoff===
'''Explanation:''' Either you entered an invalid userid, or the password for the userid is incorrect. If an external authorizer is active, you may not be authorized to use Model 204, or you may have entered an invalid account code if account validation is active.
Available with zap 75Z279: The "Enter logoff" text is displayed for this message if the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter is set to 19.

Response: Retry the login with a valid user ID and the correct password. If you are still unable to log in, contact your system manager to verify your userid and password.

System manager response: Issue the LOGLST command to determine if the user has a user ID and, if so, find out his or her password from your hardcopy file record and give the correct password to the user. If you do not have any record of the password or if the user ID does not exist, change the entry or add a new entry to the password table for the user with the LOGCTL command.

If an external authorizer is active (ACF2, Security Server (formerly RACF), Top Secret), use the appropriate commands for that system to verify that the user is a valid system user.
If Model 204 is validating the authority of the user to enter the system, verify that the user has the appropriate authorization. In addition, if the default user ID has been set to blanks, or, if the default user ID cannot log in, no CCASTAT defined users may log in.

Finally, if account validation is active, ensure that the userid has the authority to use the account code that was entered.

Return codes: C 0 4 AUDITER

----

===M204.0434: NJBUFF set to %C===

'''Explanation:''' The NJBUFF parameter was set to an invalid value. NJBUFF must be equal to:
<ul>
<li>One (1), or </li>
<li>Value of the NSERVS parameter, plus NSUBTKS parameter, plus 1.</li>
</ul>
NJBUFF specifies the number of journal buffers allocated by Model 204 during initialization.
Response: Notify the system manager. 
System manager response: Reset the NJBUFF parameter to a valid value and rerun Model 204.
Return codes: I 0 0 AUDITAD

----

===M204.0761: ATRPG*ASTRPPG exceeds <var class="term">maxentries</var>===

'''Explanation:''' You attempted to initialize a file that was created with invalid parameters. The number of dictionary entries is determined by the product of the parameters ATRPG and ASTRPPG. The maximum allowed product is 4000 (attribute dictionary entries), or 32000 for a FILEORG=x'100' file. The INITIALIZE command is rejected.

'''Response:''' The file must be recreated. Retry the CREATE command specifying ATRPG and ASTRPPG parameter values such that the product of the two is less than <var class="term">maxentries</var>.

'''Return Codes:''' C 0 4 AUDITER
----

===M204.0790: File too big===

'''Explanation:''' The total number of records possible in Table B exceeds 342 segments for files that do not have the FILEORG X'200' bit set and 1024 segments for files that have the FILEORG X'200' bit set.
The number of potential record numbers per segment is 49,152.
The number of possible segments in Table B is calculated by the following formula:
((BSIZE * BRECPPG) / 49,152)) + (1 if remainder not 0)

If the result exceeds 342 or 1024 respectively too many segments result and MODEL 204 rejects the CREATE command.
 '''File manager response:''' Make the file smaller (by specifying a smaller BSIZE or smaller BRECPPG), or divide the file into smaller pieces and use the file group feature to process them as a single logical file.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.0797: BSIZE*BRECPPG exceeds maximum value===

'''Explanation:''' The product of BSIZE and BRECPPG must not exceed 16,777,216 for regular Model 204 files (which do not have the FILEORG X'200' bit set) and 50,331,648 for files that have the FILEORG X'200' bit set. These numbers specify the maximum number of records allowed in a single Model 204 file.

The CREATE or INCREASE command is rejected.
 '''File manager response:''' Retry the command, specifying values for BSIZE and BRECPPG so that BSIZE*BRECPPG does not exceed the limit. See [[Managing file and table sizes]] for more information.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.1050: CCATEMP full: <var class="term">operation</var> or <var class="term">pooltype</var>===
Explanation: The operation being performed required an extra page from CCATEMP, but there were no free pages available. CCATEMP is defined by the system manager and provides a set of work pages that are assigned on request to various users. If a request gets this message, it might be because some other user is holding a large number of CCATEMP pages.

The message specifies either the operation being performed, or the section ("pool") of CCATEMP that was full.

<var class="term">operation</var> can be one of:
<ul>
<li>$BLDPROC</li>
<li>"USE PROCEDURE" COMMAND</li>
<li>WHILE INITIALIZING SORT</li>
<li>FOR FRV KEYS</li>
<li>WHILE GENERATING RECORDS TO BE SORTED</li>
<li>WHILE GENERATING ORDERED INDEX SORTED RECORDS</li>
<li>WHILE PERFORMING SORT</li>
</ul>

<var class="term">pooltype</var> can be one of:
<ul>
<li>SMALL MODEL PAGE POOL</li>
<li>SMALL MODEL PAGE POOL AND EXPANSION PAGE POOL</li>
</ul>
The current request is cancelled.

If the operation was $BLDPROC or USE PROCEDURE COMMAND, then the temporary procedure that was being written is deleted, except for its very last CCATEMP page, which is retained for information purposes.

In some cases the user is restarted and, if the user was in the process of updating any files, MODEL 204 marks them physically inconsistent.

CCATEMP pages below 64K are allocated from the small model pool.
CCATEMP pages above 64K are allocated from the expansion area pool.

The <var class="term">pooltype</var> specified in the message indicates whether you exceeded the capacity of the small model pool or both the small model and expansion area pools.

Response: Notify your system manager.
System Manager response: Recover the physically inconsistent files using one of the following procedures:
<ul>
<li>Roll back/roll forward</li>
<li>File reorganization procedure described in [[File reorganization and table compaction]]</li>
<li>The RESTORE command for restoring previously dumped copies</li>
</ul>
This message is informational, but it indicates a need to increase the space allocation for CCATEMP. As the size of CCATEMP is fixed at initialization, it is necessary to bring down MODEL 204 to increase it.

Return codes: E 60 60 AUDITAD CANCEL NOTERM OPR

----

===M204.1052: LOUTPB %C TO %C===
'''Explanation:'''
LOUTPB has been increased or decreased, to the value given in the message.
With a full-screen terminal the value is 1.5 times the minimum for that model number, rounded
up to a multiple of 8.
A model 2 terminal results in a LOUTPB of 3200.
A model 5 terminal results in a LOUTPB of 5664.
If NBKPG is greater than 0, the largest allowable value for LOUTPB is PAGESZ
minus 40, so the value can be decreased for this reason.
'''User Response:''' No response is needed. This message is for information only.
 '''Return Codes:''' I 0 0 AUDITAD
----

===M204.1060: %C not allowed with non swappable servers===
'''Explanation:''' The service requested is not compatible with non-swappable servers.
'''System Manager Response:''' Remove any non-swappable server settings and restart Model 204 to repeat the service.
'''Return Codes:''' E 0 4 AUDITMS
----

===M204.1131: Can't <var class="term">action</var>===

'''Explanation:''' The procedure action cannot be taken for one of the following reasons:
<ul>
<li>The procedure is in use by another user.</li>
<li>The procedure is not in the file.</li>
<li>The user does not have the correct privileges to change the procedure.</li>
<li>If a RENAME or ASSIGN has been attempted, the alias might already exist.</li>
</ul>
'''Response:''' Make sure that the procedure name is spelled correctly.
If the named procedure is in use, retry the command when the procedure is no longer in use. Otherwise, arrange to place the
procedure in the file or to obtain the privileges to change the procedure.
 '''Return Codes:''' C 0 4 SUFFIX AUDITER

----
The return codes for message M204.1149 have changed.

===M204.1149: <var class="term">parameter_name</var> has been set to its minimum|maximum value: <var class="term">value</var>===

'''Explanation:''' You have attempted to reset a parameter either below the minimum or above the maximum allowed for it. Model 204 has reset the parameter to the correct minimum or maximum.
 
'''Response:''' Retry the command with a value within the correct range, or leave the value as is, since Model 204 has already reset the parameter to the correct minimum or maximum.
For PARAMETER=ESIZE, if you specify:
<ul>
<li>A zero value, which is the equivalent of Not Applicable, no pages are allocated for Table E.</li>
<li>A non-zero value, then the minimum of 20 pages allocated for Table E is enforced.</li>
</ul>
'''Return Codes:''' I 0 0 AUDITMS

----

===M204.1167: ITBL full -- argument string ignored===

Explanation: Model 204 stores the arguments passed by the <var>INCLUDE</var> command ($READ and dummy string (??) responses) in the ITBL server table. If the storage allocated to ITBL is too small to accommodate the number and size of the arguments being passed, the argument string is ignored. 

For example:
In your include command <code>INCLUDE HOTEL,GRAND,BUDAPEST</code>, the procedure named HOTEL is being passed the arguments GRAND and BUDAPEST. However, the M204.1167 message indicates that the storage allocated to ITBL is too small to accommodate those arguments. Consequently, the argument string <code>GRAND,BUDAPEST</code> is ignored. You will be prompted to provide those arguments, one at a time, as required for the number of $READ statements and dummy string substitutions encountered in the procedure.
Response: Use the <var>[[VIEW command|VIEW]] LITBL</var> command to determine the current size of ITBL; then use the <var>[[UTABLE command|UTABLE]] LITBL</var> command to increase its size. A 10-20% increase should be sufficient in most cases.
Return Codes: C 0 4 AUDITER

----

===M204.1260: {Field|Fieldgroup} was previously defined with different attributes, new {field|fieldgroup} options ignored===

Explanation: A DEFINE FIELD or a DEFINE FIELDGROUP command has attempted to define an existing field or field group with different attributes.
Response: To redefine the attributes of the field or field group, you must issue the REDEFINE FIELD or the REDEFINE FIELDGROUP command. Notify your file manager.
Return Codes: C 0 4 AUDITER
----

===M204.1307: %C logon rejected - <var class="term">reason text</var> (reason code: %X)===

Explanation: The MODEL 204 3270 terminal handler has rejected a logon request from a 3270 terminal for the reason stated. The following reason codes are defined:
<ol>
<li>There are no control blocks available for new logons. Increase the number of IODEV 7 terminal definitions. The reason text is: NOT ENOUGH 3270 TERMINALS.</li>
<li>The terminal has been defined with a non-3270 transmission services profile. The LU type must be 2. The reason text is: LU TYPE NOT = 2.</li>
<li>The terminal has been defined to require definite responses to messages it sends inbound to the host. The transmission services profile must be 3. 
The reason text is: TS PROFILE NOT = 3.</li>
<li>There has been an error on this terminal. This is a retryable error. The reason text is: LOSTERM SET FOR THIS TERMINAL.</li>
<li>The terminal definition is in use. This error should not occur. The reason text is: TERMINAL ALREADY IN USE.</li>
</ol>
System Manager Response: Contact your VTAM systems programmer to correct the VTAM definition.
Return Codes: E 0 4 AD SAVE NOTERM OPR
----
===M204.1346: Server area greater than cylinder capacity for this device. Cylinder size = <var class="term">nnn</var> BYTES.===
Explanation:
The number of bytes specified for the largest server area (SERVSIZE)
is greater than <var class="term">nnn</var>, the number of bytes contained in a cylinder for
the type of disk device on which your CCASERVR (CCASRVR for DOS) data set resides.
System Manager Response: Do one of the following:
<ul>
<li>ensure that the largest SERVSIZE value does not exceed <var class="term">nnn</var></li>
<li>place your server data sets on a type of disk device that has a
larger cylinder capacity</li>
<li>place CCASERVR in storage. (See the "CCASERVR in Storage feature" section in the <var class="book">Rocket Model 204 System Manager's Guide</var>.)</li>
</ul>
'''Return Codes:''' C 96 96 AUDITER
----
===M204.1381: (new informational message for REGENERATE)===
M204.1381 is a new informational message issued during REGENERATE to help verify that the journal data provided in CCAGEN is from the correct CCAJRNL.

The 58 bytes printed are the journal header of each journal block. (Journal headers are described in the [[Using system statistics#Header entries (Type 0)|Header entry formats]] table.)

The message has four variations, which always appear:
<ol>
<li>
M204.1381: CCAGEN: FIRST 5 CCAJRNL BLOCKS + LAST BLOCK IN HEX
Explanation: The first 58 bytes, in hex, of the first five CCAJRNL blocks and the last CCAJRNL block read from CCAGEN follow in CCAAUDIT.
</li>
<li>M204.1381: PASS1: <var class="term">hex representation of data</var></li>
<li>M204.1381: LASTB: <var class="term">hex representation of data</var></li>
<li>
M204.1381: CCAGEN BLOCK COUNT: <var class="term">nnnn</var>
Explanation: The count of CCAJRNL blocks read from CCAGEN.
</li>
</ol>
Example

This example shows the first 5 CCAJRNL blocks and the last block read from CCAGEN during pass 1 of REGENERATE.
M204.1381: CCAGEN: FIRST 5 CCAJRNL BLOCKS + LAST BLOCK IN HEX
M204.1381: PASS1: 006000020113214F155421910000000000CB...
M204.1381: PASS1: 0AD000020113214F155421910000000100CB...
M204.1381: PASS1: 07BF008A0113214F155421920000000200CB...
M204.1381: PASS1: 0B5E00020113214F155422000000000300CB...
M204.1381: PASS1: 0AAF00120113214F155422030000000400CB...
M204.1381: LASTB: 00C900020113214F155930280000337100CB...
M204.1381: CCAGEN BLOCK COUNT: <var class="term">....</var>
Response: This message is informational only; no response is required.
Return Codes: I 0 0 AUDITAD
----

===M204.1382: Chunk size <var class="term">nn</var> used: flags=X"<var class="term">nn</var>", low=<var class="term">nn</var>, high=<var class="term">nn</var>===
Explanation: This is a debugging error message.
 
Response: No response is required.
 
Return Codes: I 0 0 AUDITMS
----

===M204.1387: Allocate failed; DDNAME=<var class="term">ddname</var>,DSNAME=<var class="term">dsname</var> could not be located===
Explanation: An attempt to allocate an existing data set, data set name=<var class="term">dsname</var>, failed because the specified dsname was not found in the catalog or the catalog could not be accessed.
M204.1387 replaces M204.1070: ALLOCATE FAILED - <var class="term">reason</var> with additional information regarding the failure of the ALLOCATE command. However, M204.1070 remains in use by Janus/TCPIP for a different purpose.
Response: Correct the data set name or ensure that the data set exists and is cataloged.
Return Codes: C 0 4 AUDITER
----

===M204.1388: CHUNK size exceeds maximum of <var class="term">nnn</var>===
On a DEFINE field command, the chunk size specified is too large.
User response: Specify a chunk size less than or equal to the maximum.
Return codes: C 0 4
----

===M204.1393: CHUNK clause not of format "CHUNK <var class="term">chunkSize</var> FOR <var class="term">chunkTarget</var>"===

'''Explanation:''' On a DEFINE FIELD, the syntax of the CHUNK clause was not in the format shown in this message.
 '''File manager response:''' Correct the DEFINE FIELD command that has the incorrect CHUNK clause syntax.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1394: CHUNK <var class="term">chunkSize</var> value invalid: <var class="term">reason</var>===

'''Explanation:''' On a DEFINE FIELD, the value specified for the size of a CHUNK is invalid;
"reason" indicates why.
 '''File manager response:''' Correct the DEFINE FIELD command that has the invalid CHUNK size.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1395: CHUNK target field invalid type: <var class="term">reason</var>===

'''Explanation:''' On a DEFINE FIELD, the field specified as a CHUNK target is not a field type that can be used as a chunk target, for the reason specified.
 '''File manager response:''' Correct the DEFINE FIELD command containing the invalid CHUNK target type.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1396: CHUNK fields must be INVISIBLE ORDERED NUMERIC===

'''Explanation:''' On a DEFINE FIELD, an attempt was made to create a CHUNK field that was not INVISIBLE ORDERED NUMERIC, which is a requirement of chunk fields.
 '''File manager response:''' Correct the DEFINE FIELD command that has the invalid CHUNK target type.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1397: A CHUNK field was defined, %F may no longer be opened with M204 releases prior to V7R5===
'''Response:''' This is an informational message. No action is required.
 '''Return Codes:''' I 0 0 AUDITMS

----

===M204.1399: Same server area defined for server above the bar and non swappable server===
Explanation: The same server table has been defined in SERVNSA and SERVGA.
 '''Response:''' Correct the SERVNSA and/or SERVGA settings.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.1400: Server areas ATB require server swapping in memory===
Explanation: Parameters indicated that server areas ATB were used in the run where CCASERVR data set was defined.
 '''System Manager Response:''' Either remove the server areas ATB parameters or use server swapping in memory.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.1402: Invalid value for chunk target: <var class="term">fname</var>='<var class="term">val</var>'; values must be -999999999999999 -> 999999999999999===
Explanation: If a chunk target is any field type besides DATETIME, any value stored in it must be within the range shown in the error message.
 Response: Correct the value being stored.
 System manager response: Correct the value being stored.
 Return Codes: C 0 4 CANCEL


----

===M204.1403: Increase SERVGSZ to at least %C for required ATB server areas===
Explanation: The total size of ATB server areas is larger than the ATB server size defined in SERVGSZ.
 '''User Response:''' If the message is issued by the UTABLE command, decrease the size of the ATB server areas.
 '''System Manager Response:''' If the message is issued at initialization, either increase SERVGSZ or decrease the ATB server area size.
 '''Return Codes:''' E 80 80 AUDITAD OPR

----

===M204.1412: <var class="term">service</var> not allowed with ATB servers===
Explanation: The requested service is not compatible with ATB (above the bar) servers.
 System manager response: Remove the ATB server parameters and restart Model 204.
 Return Codes: E 0 4 AUDITMS

----

===M204.1433: CCAGEN: IS EMPTY ¦ CCAGEN: PERMANENT I/O ERROR===
Explanation: There were no valid records found in the journal(s) pointed to by CCAGEN, or a permanent I/O error was encountered.
 System manager response: Verify that you have the correct journal(s) for the run. If I/O errors were detected while reading in CCAGEN, the appropriate error messages will have been issued before this message. Correct the error and rerun media recovery. If the problem remains unclear, contact Technical Support and have the following documentation available:
<ul><li>Audit trail</li>
<li>Snap dump</li>
<li>UTILJ output for CCAGEN dataset</li></ul>
Return Codes: C 0 4 AUDITER

----

===M204.1489: Not enough file space to continue procedure definition - %F===
Explanation: There is no room in the file to store the procedure being entered with the PROCEDURE command.

<table>
<tr><td>If…</td><td>Then Model 204…</td></tr>
<tr><td>Error occurs after the first line of procedure text has been stored</td><td>Keeps the partial procedure</td></tr>
<tr><td>You are entering the text at your terminal</td><td>Ends procedure definition immediately</td></tr>
<tr><td>Procedure text is supplied by another procedure</td><td>Flushes the remainder of the input</td></tr>
<tr><td>Procedure text is supplied in a batch input stream (CCAIN)</td><td>Flushes the remainder of the procedure text and resumes processing after the END PROCEDURE command</td></tr>
</table>

Response: Create space in the file by deleting unwanted procedures or increasing Table D with the INCREASE command. Replace the partial procedure using the PROCEDURE command, or use the EDIT command to supply the missing text.

Return Codes: C 0 4 CANCEL AUDITER

----
===M204.1508: %<C userid> is not authorized to use Model 204===
Message M204.1508 has been updated to include the actual user ID of the unauthorized user.
Explanation: This user ID does not have the authority to use Model 204. Login authorization to Model 204 is defined by your installation security officer or system manager.

Response: Ask your installation security officer or system manager to authorize you for logging into Model 204.
System manager response: Contact the installation security officer or issue the appropriate external security system commands to give the user’s logon ID the authority to use Model 204. Refer to the [[Security_interfaces_overview|Security interfaces pages]] for instructions.

Return Codes: C 0 4 AUDITER

----

===M204.1587: FSCB full, IMAGE too large: LFSCB required = <var class="term">num</var>, bytes available in FSCB = <var class="term">num</var>===
Explanation: The value specified in an <var>Identify</var> statement with
the <var>Len</var> or <var>Occurs</var> option causes the size of the associated <var>Image</var> to
overflow the full screen buffer (FSCB). The FSCB is a server work area
that is used to hold a compiled Image definition.
'''Response:''' Use the <var>VIEW LFSCB</var> command to determine the current
size of the FSCB. Use the <var>UTABLE</var> command to increase the value of the
<var>LFSCB</var> parameter. Check the <var class="product">SOUL</var> request for programming errors
that might cause the value specified in the <var>Identify</var> statement to be
too large. Retry the request.
'''Return Codes: '''C 0 4 CANCEL AUDITER 

----

===M204.1589: Maximum IMAGE length is 32767: LFSCB required = <var class="term">num</var>===
Explanation: An attempt has been made to define an image greater than 32K.
'''Response:''' Redefine the image so that it is not greater than the maximum length of 32767.
'''Return Codes:''' C 0 4 CANCEL AUDITER

----
===M204.2126: User's pushdown list overflowed===

'''Explanation:''' The user's pushdown list is an internal stack for maintaining state information for user threads across internal Model 204 subroutines. The user pushdown list lives in each user's server. Its size requirement depends on the complexity of the command or User Language request.

This message is issued whenever Model 204 detects that pushdown list data has spilled into adjacent control structures. Because of potential corruption the user is restarted.
 '''Response:''' Increase the size of the user pushdown list by using the LPDLST parameter of the UTABLE command. Notify your system manager.
 '''System Manager Response:''' If this becomes a frequent occurrence, consider more permanent changes to LPDLST and SERVSIZE, since the pushdown list is a server component.
 '''Return Codes:''' C 0 4 CANCEL
----
===M204.2329: <var class="term">subsystem_name</var> at <var class="term">location_name</var> unavailable===
Explanation: The indicated subsystem at the specified node is not available for use due to one or more errors occurring at the specified node during start or login processing.
Response: Notify the system manager or try again later.
System manager response: If the subsystem is started, stop the subsystem and resolve communications errors or other errors which occurred at the specified node. After resolving error, use the START SUBSYSTEM command to make the subsystem available for general use. Check to make sure that the LOCATION parameter was set properly in the CCAIN input stream for the Online.
Return Codes: C 0 4
----

===M204.2551: {FPL|FCT PG1} is invalid for file: <var class="term">filename</var>===

'''Explanation:''' If the message says FPL, then the FPL (file parameter list) for the associated file is invalid. This could be the result of an incorrect DD, FILEDEF or DLBL statement.

If the message says FCT PG1, then the existence page array page is invalid.

'''File manager response:''' If the DD, FILEDEF or DLBL statement is correct and points to the correct data set, then the file must be restored from a backup.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.2651: Not all threads processed for IODEV %C===
Explanation: The run is terminated because either:
<ul>
<li>The number of threads specified by NUSERS has been initialized, but there are fewer users of the specified IODEV type than expected.</li>
<li>The DUPTERM number specified by the IODEV card could not be initialized because it exceeded the number of NUSERS.</li>
</ul>
Response: Check that NUSERS matches the total of the listed IODEVs, plus one extra for USER 0. Check also the NOTERM/DUPTERM parameter for the specified IODEV card.
Return Codes: E 80 80 ER
----
===M204.2719: Open %C failed. Update statements already compiled, read only privileges insufficient===
Explanation: The OPEN or OPENC User Language statement was issued from a request to reopen a file with read-only privileges. However, that request had already been compiled with update statements against the file.
Response: In a User Language request, you cannot use the User Language OPEN or OPENC statement to reopen a file with read-only privileges, if that request contains updates statements against the same file.
Descriptor code: C 0 4 CANCEL
----
===M204.2739: Parameter <var class="term">parm</var> cannot be reset on user 0’s parameter line: value ignored===
Explanation: You reset parameter <var class="term">parm</var> on the User 0 parameter line, but the parameter cannot be set there. The value is ignored, the default value for this parameter remains in effect.
Response: Remove <var class="term">parm</var> from the User 0 parameters, since it will not change the value of the parameter.
Descriptor code: E 0 4 AD
----
===M204.2746: XSIZE*XRECPPG may not be 1 nor exceed 536870911===
Explanation: The product of XSIZE and XRECPPG must not exceed 16777216 times 32 minus one, or 536870911. This specifies the maximum number of extension records allowed in a single Model 204 file when using Table X. Also, setting both XRECPPG and XSIZE to 1 is invalid.
The CREATE command is rejected.
Response: Retry the command specifying values for XSIZE and XRECPPG whose product does not exceed the 526870911 limit. Refer to the <var class="book">Rocket Model 204 File Manager’s Guide </var>for more information on file sizes.
Descriptor code: C 0 4
----

===M204.2774: Another command command is in progress===

Explanation: An INCREASE or DECREASE command or auto increase is taking place while another INCREASE, DECREASE, or auto increase has not finished yet.
 File manager response: Repeat the command after the completion of the auto increase or previous INCREASE or DECREASE command.
 Descriptor code: C 0 4

----

===M204.2826: %F %C compaction not allowed===

'''Explanation:''' An attempt was made to compact a file created prior to Model 204 version 6.3.
 '''File manager response:''' Reorganize the file using Model 204 version 6.3.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2831: Updates to DTS files not supported in this environment===
Explanation: DTS files cannot be updated in IFAM, SQL, or PQO environments.
Response: Do not attempt to update DTS file.
Return Codes: C 0 4
----
===M204.2833: Fields cannot be defined in a file with ATRPG*ASTRPPG>4000===
Return Codes: C 0 4
----
===M204.2836: Value of parameter %C invalid—reset to %C===

'''Explanation:''' This is an informational message only.

A parameter was specified with an incorrect value. It has been reset to an internally calculated value that will accommodate other parameter settings. See the description of the parameter named to see what that calculation involves.
 '''System Manager Response:''' The parameter has been reset. No response is required.
 '''Return Codes:''' I 0 0 AUDITMS
----

===M204.2838: %C only valid in FILEORG X’100’ files===
Return Codes: C 0 4
----
===M204.2839: %C is a %C, not a %C===
Return Codes: C 0 4 ECHO
----
===M204.2841: Remote fieldgroups not supported===
Return Codes: C 0 4 ECHO
----
===M204.2842: Invalid context for fieldgroup===
Return Codes: C 0 4 ECHO
----
===M204.2843: Maximum fieldgroup id exceeded in record %R in %F===
Return Codes: C 0 4 CANCEL
----
===M204.2844: Mix of fields and fieldgroups, name <nowiki>=</nowiki>===
Return Codes: C 0 4 SUFFIX ECHO
----

===M204.2845: Invalid fieldgroup context for %C===
Explanation: The $function was used outside of field group context.
Descriptor code:C 0 4 SUFFIX ECHO
----
===M204.2846: Invalid fieldgroup context for %C===
Return Codes: C 0 4 CANCEL
----
===M204.2847: Fieldgroup context lost in record %R in %F===
Return Codes: C 0 4 CANCEL
----
===M204.2848: Invalid fieldgroup id: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2849: Required keyword %C missing===
Return Codes: X 0 4 ECHO
----

===M204.2850: %C value missing===
Return Codes: C 0 4
----
===M204.2851: %C value "%C" too big, must be <%C bytes===
Return Codes: C 0 4
----

===M204.2852: Update to missing fieldgroup occurrence in record %R in %F===
Return Codes: C 0 4 CANCEL
----

===M204.2853: %C not allowed for EXACTLY-ONE field===
Return Codes: C 0 4
----

===M204.2854: Attempt to do %C for EXACTLY-ONE field: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2855: Field depth+length unrepresentable in record %R in %F===
Return Codes: C 0 4 CANCEL
----

===M204.2856: Fieldname variable %C: expected %C, got %C===
Return Codes: C 0 4 CANCEL
----

===M204.2857: %C field not allowed for %C field===
Return Codes: C 0 4
----

===M204.2858: Fieldgroup context mismatch between COUNT-OCCURRENCES-OF field and counted field===
Return Codes: C 0 4
----

===M204.2859: New automatic field not allowed for non-empty file===
Return Codes: C 0 4
----

===M204.2860: Field %C already has a COUNT-OCCURRENCES-OF field===
Return Codes: C 0 4
----

===M204.2861: Occurrence counter %C overflowed===
Return Codes: C 0 4 CANCEL
----

===M204.2862: Attempt to update automatic field %C===
Return Codes: C 0 4 SUFFIX ECHO
----

===M204.2863: Attempt to do %C for automatic field: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2865: Attempt to %C invalid datetime value: %C = %C===
Return Codes: C 0 4 CANCEL
----

===M204.2866: File already has %C field===
Return Codes: C 0 4
----

===M204.2867: Fieldgroup %C already has %C field===
Explanation: If you try to define a second update tracker field of the same type for the same field group, you will invoke message 2867, where %C represents:
<ul>
<li>A CREATE-TIME</li>
<li>A CREATE-TIMEUTC</li>
<li>A CREATE-USER</li>
<li>AN UPDATE-TIME</li>
<li>AN UPDATE-TIMEUTC</li>
<li>AN UPDATE-USER</li>
</ul>
Return Codes: C O 4
----

===M204.2868: MINLOBE must be between 0 and %C===
Return Codes: C 0 4
----

===M204.2869: Change refused: MINLOBE > 0 for File <var class="term">filename</var> field <var class="term">fieldname</var>===
'''Return Codes:''' C 0 4 AUDITER
----

===M204.2870: Change refused: MINLOBE > 0 for File <var class="term">filename</var> field <var class="term">fieldname</var>===
'''Return Codes:''' C 0 4 CANCEL AUDITER
----

===M204.2871: Fieldgroup context mismatch between CONCATENATION-OF field and COMPONENT field===
Return Codes: C 0 4
----

===M204.2872: Concatenation value too long for field %C===
Return Codes: C 0 4 CANCEL
----

===M204.2873: Concatenation field %C component field %C contains separator character===
Return Codes: C 0 4 CANCEL
----

===M204.2874: Attempt to %C a value that's %C: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2875: Concatenation list invalid: %C===
Return Codes: C 0 4
----

===M204.2876: Invalid %C value: %C===
Return Codes: C 0 4
----

===M204.2877: WITH clause invalid: %C===
Return Codes: C 0 4 ECHO

----

===M204.2878: WITH clause invalid: field %C in %F %C===
Return Codes: C 0 4 CANCEL
----

===M204.2879: Remote id %C mode %C===
Return Codes: I 0 0 SAVE NOTERM OPR

----

===M204.2880: Memory datasets cannot be part of multi-dataset file===
Return Codes: C 0 4

----

===M204.2881: Data conversion error===
Return Codes: C 0 4 CANCEL

----

===M204.2882: Recovery journal (CCARF) version %C is not supported===
Explanation: A CCARF data set was provided as input to a recovery step, but that CCARF data set was produced by a different version of Model 204 than the version that is running recovery.
 System manager response: Correct the data set name referenced in CCARF and ensure that it was produced by the version of Model 204 that you are using to run recovery.
 Return codes: E 52 52 OPR

----

===M204.2883: Mix of journal versions in recovery CCARF===
Return codes: E 52 52 SNAP OPR

----

===M204.2884: {Field|Fieldgroup} was previously defined as a {fieldgroup|field}, new definition ignored===
Return Codes: C 0 4

----

===M204.2885: Invalid fieldgroup id: <var class="term">fieldgroup</var>===
Return Codes: C 0 4 CANCEL

----

===M204.2886: Fieldgroup id %C already exists in record %R in %F===
Return Codes: C 0 4

----

===M204.2903: FILEORG=X'100' is not supported during FLOD/FILELOAD===
Return Codes: E 0 8
----

===M204.2916: %C requires at least one area to be set in %C===
'''Explanation:''' When the size of a non-swappable server area is indicated (SERVNSSZ), at least one non-swappable server area must be indicated in SERVNSA.
 '''Operator response:''' Correct the SERVNSA parameter setting.
 '''Return Codes:''' E 0 4 AUDITMS
----

===M204.2921: Server areas above the bar are not supported in VSE===
'''Explanation:''' Non-swappable server areas ATB are not supported in VSE.
 '''Operator response:''' Remove the parameters for non-swappable server areas.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.2922: %C bit setting is not valid===
'''Explanation:''' The bit setting in [[SERVNSA parameter|SERVNSA]] is not valid.
 For release 7.4, valid bits are: X'02000000'
 For release 7.5, valid bits are: X'02000000', X'00800000', X'00004000', and X'00002000'
 '''Operator response:''' Correct the SERVNSA setting.
 '''Return Codes:''' E 0 4 AUDITMS
----

===M204.2933: Module version mismatch, KOMM=%C, %C=% C===
'''Return Codes:''' E 0 4 SNAP

----
===M204.2934: FILEORG X<nowiki>'200'</nowiki> not supported for hashed or sorted file organizations===
'''Explanation:''' Hashed or sorted files must be 16M files. The CREATE FILE command
is rejected.
 '''File manager response:''' Remove the conflicting FILEORG parameter and reissue CREATE FILE.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.2935: {CHUNK|CHUNK target} fields may not be RENAMED or DELETED===
'''File manager response:''' Do not attempt to RENAME or DELETE chunks or chunk targets.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2936: A CHUNK field of size <var class="term">nnn</var> already exists for this field===
'''Explanation:''' For a given CHUNK target field, duplicate chunk sizes are not permitted.
 '''File manager response:''' Correct the DEFINE FIELD that caused the message.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2937: CHUNK SIZE: <var class="term">nnn</var> is not an integral multiple/divisor of the existing CHUNK size: <var class="term">nnn</var>===
'''Explanation:''' A CHUNK field's chunk size must be an integral multiple/divisor of all other chunk's sizes for a given chunk target.
 This message identifies the existing chunk size that conflicts with the new one.
 '''File manager response:''' Correct the DEFINE FIELD that caused the message.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2938: You may not define more than %C chunks for a field===
'''Explanation:''' A given chunk target can have at most 20 chunks defined.
 '''File manager response:''' Do not try to define more than 20 CHUNK fields for any given CHUNK target field.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.2939: %C has been set to its %C value: %C===
'''Explanation:''' TBD
 '''Return codes:''' I 0 0 AUDITMS

----

===M204.2940: Use of filename after INITIALIZE keyword discouraged because it gave different results prior to version 7.5===
'''Explanation:''' This message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if it was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
 
If you have entered the name of the file being initialized AFTER the INITIALIZE command keyword, you can either correct the command (that is, remove the filename after the INITIALIZE command keyword) or use the MSGCTL M204.2940 command as described below so that the command can continue to work.
 '''File manager response:''' The most direct response is to correct the command to conform to the proper syntax, that is, remove extraneous strings after the INITIALIZE command keyword.
 '''System manager response:''' If the file manager has chosen to keep the filename after the INITIALIZE command keyword, and the filename is the same as the name of the file being initialized, you can have the following command executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2940 NOCOUNT
This action represents a very special case for the NOCOUNT option of MSGCTL.
 
Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.
 
For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 
Issuing the above MSGCTL command with version 7.5 of Model 204 will not present any risk of an incorrect operation of INITIALIZE.
A word of caution, however: In prior versions of Model 204, a filename after the INITIALIZE command keyword is NOT checked against the name of the file being initialized. Therefore the use of the filename after the INITIALIZE command keyword could be a risky practice if such a command might be used in a prior version of Model 204.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2941: File being initialized does not match name given after INITIALIZE command: %C===
'''Explanation:'''
This message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if it was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
 
In some cases, users have entered the name of the file being initialized AFTER the INITIALIZE command keyword, but this message indicates that whatever string you entered after the INITIALIZE command keyword is not the name of the file being initialized.
 '''File manager response: '''
Correct the command. The most direct response is to correct the command to conform to the proper syntax: that is, remove extraneous strings after the INITIALIZE command keyword.
 
However, if the system manager has performed a MSGCTL M204.2940 NOCOUNT command, and you want to enter the correct filename on the INITIALIZE command, that will allow the INITIALIZE operation to proceed.
 
'''System manager response: '''
 If the file manager is unable to correct the INITIALIZE command, you can have the following commands executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2940 NOCOUNT
MSGCTL M204.2941 NOCOUNT
These actions represent a very special case for the NOCOUNT option of MSGCTL.
 Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but it does not directly affect the operation which issued the error message.
 For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 Issuing MSGCTL M204.2941 NOCOUNT is not recommended, because this results in what might appear to be checking of the filename when in fact it is not checked.
 Issuing MSGCTL M204.2940 NOCOUNT does not present any risk with version 7.5 of Model 204, but, as discussed in the System Manager response section of message 2940, this practice should be done with caution.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2942: Extraneous string after field attribute list: %C===
'''Explanation:''' This message indicates that the format of the INITIALIZE command as entered for a hashed, sorted, or record security file does not conform to the syntax of:
INITIALIZE
[SORT fldName (attributes)]
[HASH fldName (attributes)]
[RECSCTY fldName (attributes)]
In particular, it indicates that some string followed the right parenthesis (')') of the attribute list.
Prior to version 7.5, nothing after the closing parenthesis was checked.
 '''File manager response:''' Correct the command. There should be no string after the right parenthesis.
 '''System manager response:''' If the file manager is unable to correct the INITIALIZE command, you can have the following command executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2942 NOCOUNT 
This action represents a very special case for the NOCOUNT option of MSGCTL. Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.
 For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 Issuing MSGCTL M204.2942 NOCOUNT is not recommended, because if you issue this command the string after the right parenthesis will not be analyzed.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2943: Error using filename phrase for file %C: <var class="term">restriction</var>===
'''Explanation:''' This message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if it was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
 
In some cases, users have entered the name of the file being initialized AFTER the INITIALIZE command keyword, but this message indicates that the syntax requires some modification for the particular file being initialized.
 '''File manager response:''' The command should be corrected; the most direct response is to correct the command to conform to the proper syntax, that is remove extraneous strings after the INITIALIZE command keyword.
However, if the system manager has performed a MSGCTL M204.2940 NOCOUNT command, you can modify the command as indicated by the <var class="term">restriction</var> shown in the M204.2943 text.
 '''System manager response:''' If the file manager is unable to correct the INITIALIZE command, you can have the following commands executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2940 NOCOUNT
MSGCTL M204.2943 NOCOUNT
This action represents a very special case for the NOCOUNT option of MSGCTL. Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.
 
For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 
Issuing MSGCTL M204.2943 NOCOUNT is not recommended, because this bypasses the checking that is intended by the <var class="term">restriction</var> shown in the M204.2943 text.
 
Issuing MSGCTL M204.2940 NOCOUNT does not present any risk with version 7.5 of Model 204, but, as discussed in the system manager response for M204.2940, this practice should be done with caution.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2944: Should have end of <var class="term">cmd</var> command but instead found: <var class="term">string</var>===
'''Explanation:''' This message indicates that the format of the command indicated by cmd as entered does not conform to command syntax.
 '''User response:''' Correct the command, either by simply removing string and any following strings or else by correcting the command to conform to the proper syntax.
 '''File manager response:''' If the cmd in the M204.2944 text is INITIALIZE, this message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if the text was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
The command should be corrected as described in the user response above.
 '''System manager response:''' If the file manager is unable to correct the INITIALIZE command, you can have the following command executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2944 NOCOUNT
This action represents a very special case for the NOCOUNT option of MSGCTL. Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.

For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.

Issuing MSGCTL M204.2944 NOCOUNT is not recommended, because whatever string was indicated on the INITIALIZE command is not checked.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2945: Error encountered, <var class="term">cmd</var> command not performed===
'''Explanation:''' This counting error message indicates that the processing of the <var class="term">cmd</var> command was not performed. This message should be preceded by one or more messages. (If the preceding messages were not counting error messages, they might not have been displayed on the user's terminal, depending on the MSGCTL parameter setting.)
 '''User response:''' Correct any conditions indicated by the preceding messages.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2946: Error encountered, <var class="term">cmd</var> command not performed ===
'''Explanation:''' This informational message indicates that the processing of the <var class="term">cmd</var> command was not performed. This message should be preceded by one or more messages. (If the preceding messages were not counting error messages, they might not have been displayed on the user's terminal, depending on the MSGCTL parameter setting.)
 '''User response:''' Correct any conditions indicated by the preceding messages.
 '''Return codes:''' I 0 0 AUDITMS

----

===M204.2947: Module address <var class="term">address</var> length <var class="term">length</var> protected===
Explanation: This informational message is displayed during startup to show the ranges of load module protection. To see which Rocket CSECTs are being referenced, look at the module map in a snap. For more information on the load module protection facility, see the [[MODPROT parameter]] description.
 Response: No response is required.
 Return codes: I 0 0 AUDITMS

==DDGEN messages==
===DDG017: UNABLE TO PROCESS NON-TBO FILE WITH SYSOPT=4, CHANGE FILE TO TBO OR RESET SYSOPT.===
===DDG018: FICREATE UNRECOGNIZABLE. DDGEN RUN CANCELLED.===

[[#toc|Up to Contents]]

[[Category:Release notes]]

New and updated messages in Model 204 version 7.5

2015-07-30T23:17:42Z

Tbullock: Was missing "File"

[[Release_notes_for_Model_204_version_7.5|Back to 7.5 Release Notes]]

<div class="noautonum">__TOC__</div>

==M204 messages==
===Mixed case messages by default===
As of version 7.5, all Model 204 messages are issued with mixed case text by default unless [[UPCASMSG parameter|UPCASMSG]] is set.
===M204.0141: Bug .. duplicate file name in cp record===
Explanation: A duplicate file name was encountered while attempting to add a deferred update dataset to the file directory during recovery. This indicates a potential problem in the Model 204 software.

System Manager Response: Contact Technical Support with the following documentation:
<ul>
<li>Audit trail from the previous run</li>
<li>Journal from the previous run</li>
</ul>
Return Codes: E 0 4 AD OPR

----

===M204.0204: Parameter <var class="term">parmName</var> obsolete and not reset===
'''Explanation:''' Writing records to the SMF data set no longer requires the installation of an SVC. The
SMFSVC parameter is therefore obsolete and cannot be reset.
 '''System Manager Response:''' No response required.
 '''Return Codes:''' I 0 0 AUDITMS

----

===M204.0316: Recursive ON units exceed MAXOND: Evaluation stopped===
'''Explanation:''' During evaluation, one or more ON units was entered recursively. When the number of recursions exceeded MAXOND, the evaluation was terminated.
 '''System Manager Response:''' This message might indicate a logic error in the program. Inform the program author.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.0332 and M204.0336===
These messages indicate problems with the CRAM interface.
The visibility of these messages has been improved by:
<ul>
<li>writing the message to the operator and the JESLOG
<li>writing the message as an ER line in CCAAUDIT
<li>setting the return code to 80
</ul>

====M204.0332: RC ''nn'' from CRFS OPEN====
'''Explanation:''' The run has failed to initialize due to problems with the CRAM interface.
The possible formats of this message are:

Format 1: RC nn from CRFS OPEN/PUT/GET

Format 2: ECB postcode from CRFS PUT/GET
<ul>
<li>
Format 1 indicates that Model 204 module CRFS attempted to open channel, send a message down the channel, or receive a message from a channel. CRAM was unable to satisfy the request. The message states the return code and the
operation attempted.</li>
<li>
Format 2 indicates that Model 204 module CRFS received an unexpected post code from CRAM while attempting an I/O operation on a channel. The message states the post code and the operation attempted.
</li>
</ul>
Possible return codes include the following values:
<table>
<tr class="head"><th>Value</th> <th>Description</th>
<tr><td>4</td> <td>INVALID FUNCTION</td></tr>
<tr><td>8</td> <td>CB FORMAT ERROR</td></tr>
<tr><td>16</td> <td>(OPEN MAST) CHANNEL ALREADY OPEN</td></tr>
<tr><td>20</td> <td>(OPEN USER) NO USER LINES FREE</td></tr>
<tr><td>24</td> <td>(OPEN) SUBTASKS NOT PROPERLY OPENED</td></tr>
<tr><td>12</td> <td>(READ/WRITE) ICB NOT OPEN</td></tr>
<tr><td>16</td> <td>(READ/WRITE) OTHER TASK HAS DIED</td></tr>
<tr><td>20</td> <td>(READ/WRITE) UNEXPECTED COMMAND</td></tr>
<tr><td>28</td> <td>NOT ENOUGH STORAGE</td></tr>
<tr><td>99</td> <td>There is no SVC defined in the IGCLM244 module and the XMEMOPT ’80’ bit must be set for an SVC-less installation</td></tr>
<tr><td>110</td> <td>(VMCF WRITE) MESSAGE LIMIT EXCEEDED</td></tr>
</table>
'''System Manager Response:''' Contact Technical Support and have the audit trail available.
 '''Return Codes:''' C 80 80 AUDITER NOTERM OPR

====M204.0336: RC ''nn'' from CRIO OPEN====
'''Explanation:''' The run has failed to initialize due to problems with the CRAM interface.
The possible formats of this message are:

Format 1: RC nn from CRIO OPEN/PUT/GET

Format 2: ECB postcode from CRFS PUT/GET
<ul>
<li>
Format 1 indicates that Model 204 module CRIO attempted to open a channel,
send a message down a channel, or receive a message from a channel. CRAM
was unable to satisfy the request. The message states the return code and the
operation attempted. For example, the return code 16 indicates that the CRAM
channel is already open.</li>
<li>
Format 2 indicates that a Model 204 CRAM interface module, such as CRFS or CRIO, received an unexpected post
code from CRAM while attempting an I/O operation on a channel. The message
shows the post code and the operation attempted.</li>
</ul>
Possible return codes include the following values:
<table>
<tr class="head"><th>Value</th> <th>Description</th>
<tr><td>4</td> <td>INVALID FUNCTION</td></tr>
<tr><td>8</td> <td>CB FORMAT ERROR</td></tr>
<tr><td>16</td> <td>(OPEN MAST) CHANNEL ALREADY OPEN</td></tr>
<tr><td>20</td> <td>(OPEN USER) NO USER LINES FREE</td></tr>
<tr><td>24</td> <td>(OPEN) SUBTASKS NOT PROPERLY OPENED</td></tr>
<tr><td>12</td> <td>(READ/WRITE) ICB NOT OPEN</td></tr>
<tr><td>16</td> <td>(READ/WRITE) OTHER TASK HAS DIED</td></tr>
<tr><td>20</td> <td>(READ/WRITE) UNEXPECTED COMMAND</td></tr>
<tr><td>28</td> <td>NOT ENOUGH STORAGE</td></tr>
<tr><td>99</td> <td>There is no SVC defined in the IGCLM244 module and the XMEMOPT ’80’ bit must be set for an SVC-less installation</td></tr>
<tr><td>110</td> <td>(VMCF WRITE) MESSAGE LIMIT EXCEEDED</td></tr>
</table>
'''System Manager Response:''' Contact Technical Support and have the audit trail available.
 
'''Return Codes:''' C 80 80 AUDITER NOTERM OPR

----

===M204.0349: Login failed (<var class="term">alternative text</var>) Enter logoff===
'''Explanation:''' Either you entered an invalid userid, or the password for the userid is incorrect. If an external authorizer is active, you may not be authorized to use Model 204, or you may have entered an invalid account code if account validation is active.
Available with zap 75Z279: The "Enter logoff" text is displayed for this message if the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter is set to 19.

Response: Retry the login with a valid user ID and the correct password. If you are still unable to log in, contact your system manager to verify your userid and password.

System manager response: Issue the LOGLST command to determine if the user has a user ID and, if so, find out his or her password from your hardcopy file record and give the correct password to the user. If you do not have any record of the password or if the user ID does not exist, change the entry or add a new entry to the password table for the user with the LOGCTL command.

If an external authorizer is active (ACF2, Security Server (formerly RACF), Top Secret), use the appropriate commands for that system to verify that the user is a valid system user.
If Model 204 is validating the authority of the user to enter the system, verify that the user has the appropriate authorization. In addition, if the default user ID has been set to blanks, or, if the default user ID cannot log in, no CCASTAT defined users may log in.

Finally, if account validation is active, ensure that the userid has the authority to use the account code that was entered.

Return codes: C 0 4 AUDITER

----

===M204.0434: NJBUFF set to %C===

'''Explanation:''' The NJBUFF parameter was set to an invalid value. NJBUFF must be equal to:
<ul>
<li>One (1), or </li>
<li>Value of the NSERVS parameter, plus NSUBTKS parameter, plus 1.</li>
</ul>
NJBUFF specifies the number of journal buffers allocated by Model 204 during initialization.
Response: Notify the system manager. 
System manager response: Reset the NJBUFF parameter to a valid value and rerun Model 204.
Return codes: I 0 0 AUDITAD

----

===M204.0761: ATRPG*ASTRPPG exceeds <var class="term">maxentries</var>===

'''Explanation:''' You attempted to initialize a file that was created with invalid parameters. The number of dictionary entries is determined by the product of the parameters ATRPG and ASTRPPG. The maximum allowed product is 4000 (attribute dictionary entries), or 32000 for a FILEORG=x'100' file. The INITIALIZE command is rejected.

'''Response:''' The file must be recreated. Retry the CREATE command specifying ATRPG and ASTRPPG parameter values such that the product of the two is less than <var class="term">maxentries</var>.

'''Return Codes:''' C 0 4 AUDITER
----

===M204.0790: File too big===

'''Explanation:''' The total number of records possible in Table B exceeds 342 segments for files that do not have the FILEORG X'200' bit set and 1024 segments for files that have the FILEORG X'200' bit set.
The number of potential record numbers per segment is 49,152.
The number of possible segments in Table B is calculated by the following formula:
((BSIZE * BRECPPG) / 49,152)) + (1 if remainder not 0)

If the result exceeds 342 or 1024 respectively too many segments result and MODEL 204 rejects the CREATE command.
 '''File manager response:''' Make the file smaller (by specifying a smaller BSIZE or smaller BRECPPG), or divide the file into smaller pieces and use the file group feature to process them as a single logical file.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.0797: BSIZE*BRECPPG exceeds maximum value===

'''Explanation:''' The product of BSIZE and BRECPPG must not exceed 16,777,216 for regular Model 204 files (which do not have the FILEORG X'200' bit set) and 50,331,648 for files that have the FILEORG X'200' bit set. These numbers specify the maximum number of records allowed in a single Model 204 file.

The CREATE or INCREASE command is rejected.
 '''File manager response:''' Retry the command, specifying values for BSIZE and BRECPPG so that BSIZE*BRECPPG does not exceed the limit. See [[Managing file and table sizes]] for more information.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.1050: CCATEMP full: <var class="term">operation</var> or <var class="term">pooltype</var>===
Explanation: The operation being performed required an extra page from CCATEMP, but there were no free pages available. CCATEMP is defined by the system manager and provides a set of work pages that are assigned on request to various users. If a request gets this message, it might be because some other user is holding a large number of CCATEMP pages.

The message specifies either the operation being performed, or the section ("pool") of CCATEMP that was full.

<var class="term">operation</var> can be one of:
<ul>
<li>$BLDPROC</li>
<li>"USE PROCEDURE" COMMAND</li>
<li>WHILE INITIALIZING SORT</li>
<li>FOR FRV KEYS</li>
<li>WHILE GENERATING RECORDS TO BE SORTED</li>
<li>WHILE GENERATING ORDERED INDEX SORTED RECORDS</li>
<li>WHILE PERFORMING SORT</li>
</ul>

<var class="term">pooltype</var> can be one of:
<ul>
<li>SMALL MODEL PAGE POOL</li>
<li>SMALL MODEL PAGE POOL AND EXPANSION PAGE POOL</li>
</ul>
The current request is cancelled.

If the operation was $BLDPROC or USE PROCEDURE COMMAND, then the temporary procedure that was being written is deleted, except for its very last CCATEMP page, which is retained for information purposes.

In some cases the user is restarted and, if the user was in the process of updating any files, MODEL 204 marks them physically inconsistent.

CCATEMP pages below 64K are allocated from the small model pool.
CCATEMP pages above 64K are allocated from the expansion area pool.

The <var class="term">pooltype</var> specified in the message indicates whether you exceeded the capacity of the small model pool or both the small model and expansion area pools.

Response: Notify your system manager.
System Manager response: Recover the physically inconsistent files using one of the following procedures:
<ul>
<li>Roll back/roll forward</li>
<li>File reorganization procedure described in [[File reorganization and table compaction]]</li>
<li>The RESTORE command for restoring previously dumped copies</li>
</ul>
This message is informational, but it indicates a need to increase the space allocation for CCATEMP. As the size of CCATEMP is fixed at initialization, it is necessary to bring down MODEL 204 to increase it.

Return codes: E 60 60 AUDITAD CANCEL NOTERM OPR

----

===M204.1052: LOUTPB %C TO %C===
'''Explanation:'''
LOUTPB has been increased or decreased, to the value given in the message.
With a full-screen terminal the value is 1.5 times the minimum for that model number, rounded
up to a multiple of 8.
A model 2 terminal results in a LOUTPB of 3200.
A model 5 terminal results in a LOUTPB of 5664.
If NBKPG is greater than 0, the largest allowable value for LOUTPB is PAGESZ
minus 40, so the value can be decreased for this reason.
'''User Response:''' No response is needed. This message is for information only.
 '''Return Codes:''' I 0 0 AUDITAD
----

===M204.1060: %C not allowed with non swappable servers===
'''Explanation:''' The service requested is not compatible with non-swappable servers.
'''System Manager Response:''' Remove any non-swappable server settings and restart Model 204 to repeat the service.
'''Return Codes:''' E 0 4 AUDITMS
----

===M204.1131: Can't <var class="term">action</var>===

'''Explanation:''' The procedure action cannot be taken for one of the following reasons:
<ul>
<li>The procedure is in use by another user.</li>
<li>The procedure is not in the file.</li>
<li>The user does not have the correct privileges to change the procedure.</li>
<li>If a RENAME or ASSIGN has been attempted, the alias might already exist.</li>
</ul>
'''Response:''' Make sure that the procedure name is spelled correctly.
If the named procedure is in use, retry the command when the procedure is no longer in use. Otherwise, arrange to place the
procedure in the file or to obtain the privileges to change the procedure.
 '''Return Codes:''' C 0 4 SUFFIX AUDITER

----
The return codes for message M204.1149 have changed.

===M204.1149: <var class="term">parameter_name</var> has been set to its minimum|maximum value: <var class="term">value</var>===

'''Explanation:''' You have attempted to reset a parameter either below the minimum or above the maximum allowed for it. Model 204 has reset the parameter to the correct minimum or maximum.
 
'''Response:''' Retry the command with a value within the correct range, or leave the value as is, since Model 204 has already reset the parameter to the correct minimum or maximum.
For PARAMETER=ESIZE, if you specify:
<ul>
<li>A zero value, which is the equivalent of Not Applicable, no pages are allocated for Table E.</li>
<li>A non-zero value, then the minimum of 20 pages allocated for Table E is enforced.</li>
</ul>
'''Return Codes:''' I 0 0 AUDITMS

----

===M204.1167: ITBL full -- argument string ignored===

Explanation: Model 204 stores the arguments passed by the <var>INCLUDE</var> command ($READ and dummy string (??) responses) in the ITBL server table. If the storage allocated to ITBL is too small to accommodate the number and size of the arguments being passed, the argument string is ignored. 

For example:
In your include command <code>INCLUDE HOTEL,GRAND,BUDAPEST</code>, the procedure named HOTEL is being passed the arguments GRAND and BUDAPEST. However, the M204.1167 message indicates that the storage allocated to ITBL is too small to accommodate those arguments. Consequently, the argument string <code>GRAND,BUDAPEST</code> is ignored. You will be prompted to provide those arguments, one at a time, as required for the number of $READ statements and dummy string substitutions encountered in the procedure.
Response: Use the <var>[[VIEW command|VIEW]] LITBL</var> command to determine the current size of ITBL; then use the <var>[[UTABLE command|UTABLE]] LITBL</var> command to increase its size. A 10-20% increase should be sufficient in most cases.
Return Codes: C 0 4 AUDITER

----

===M204.1260: {Field|Fieldgroup} was previously defined with different attributes, new {field|fieldgroup} options ignored===

Explanation: A DEFINE FIELD or a DEFINE FIELDGROUP command has attempted to define an existing field or field group with different attributes.
Response: To redefine the attributes of the field or field group, you must issue the REDEFINE FIELD or the REDEFINE FIELDGROUP command. Notify your file manager.
Return Codes: C 0 4 AUDITER
----

===M204.1307: %C logon rejected - <var class="term">reason text</var> (reason code: %X)===

Explanation: The MODEL 204 3270 terminal handler has rejected a logon request from a 3270 terminal for the reason stated. The following reason codes are defined:
<ol>
<li>There are no control blocks available for new logons. Increase the number of IODEV 7 terminal definitions. The reason text is: NOT ENOUGH 3270 TERMINALS.</li>
<li>The terminal has been defined with a non-3270 transmission services profile. The LU type must be 2. The reason text is: LU TYPE NOT = 2.</li>
<li>The terminal has been defined to require definite responses to messages it sends inbound to the host. The transmission services profile must be 3. 
The reason text is: TS PROFILE NOT = 3.</li>
<li>There has been an error on this terminal. This is a retryable error. The reason text is: LOSTERM SET FOR THIS TERMINAL.</li>
<li>The terminal definition is in use. This error should not occur. The reason text is: TERMINAL ALREADY IN USE.</li>
</ol>
System Manager Response: Contact your VTAM systems programmer to correct the VTAM definition.
Return Codes: E 0 4 AD SAVE NOTERM OPR
----
===M204.1346: Server area greater than cylinder capacity for this device. Cylinder size = <var class="term">nnn</var> BYTES.===
Explanation:
The number of bytes specified for the largest server area (SERVSIZE)
is greater than <var class="term">nnn</var>, the number of bytes contained in a cylinder for
the type of disk device on which your CCASERVR (CCASRVR for DOS) data set resides.
System Manager Response: Do one of the following:
<ul>
<li>ensure that the largest SERVSIZE value does not exceed <var class="term">nnn</var></li>
<li>place your server data sets on a type of disk device that has a
larger cylinder capacity</li>
<li>place CCASERVR in storage. (See the "CCASERVR in Storage feature" section in the <var class="book">Rocket Model 204 System Manager's Guide</var>.)</li>
</ul>
'''Return Codes:''' C 96 96 AUDITER
----
===M204.1381: (new informational message for REGENERATE)===
M204.1381 is a new informational message issued during REGENERATE to help verify that the journal data provided in CCAGEN is from the correct CCAJRNL.

The 58 bytes printed are the journal header of each journal block. (Journal headers are described in the [[Using system statistics#Header entries (Type 0)|Header entry formats]] table.)

The message has four variations, which always appear:
<ol>
<li>
M204.1381: CCAGEN: FIRST 5 CCAJRNL BLOCKS + LAST BLOCK IN HEX
Explanation: The first 58 bytes, in hex, of the first five CCAJRNL blocks and the last CCAJRNL block read from CCAGEN follow in CCAAUDIT.
</li>
<li>M204.1381: PASS1: <var class="term">hex representation of data</var></li>
<li>M204.1381: LASTB: <var class="term">hex representation of data</var></li>
<li>
M204.1381: CCAGEN BLOCK COUNT: <var class="term">nnnn</var>
Explanation: The count of CCAJRNL blocks read from CCAGEN.
</li>
</ol>
Example

This example shows the first 5 CCAJRNL blocks and the last block read from CCAGEN during pass 1 of REGENERATE.
M204.1381: CCAGEN: FIRST 5 CCAJRNL BLOCKS + LAST BLOCK IN HEX
M204.1381: PASS1: 006000020113214F155421910000000000CB...
M204.1381: PASS1: 0AD000020113214F155421910000000100CB...
M204.1381: PASS1: 07BF008A0113214F155421920000000200CB...
M204.1381: PASS1: 0B5E00020113214F155422000000000300CB...
M204.1381: PASS1: 0AAF00120113214F155422030000000400CB...
M204.1381: LASTB: 00C900020113214F155930280000337100CB...
M204.1381: CCAGEN BLOCK COUNT: <var class="term">....</var>
Response: This message is informational only; no response is required.
Return Codes: I 0 0 AUDITAD
----

===M204.1382: Chunk size <var class="term">nn</var> used: flags=X"<var class="term">nn</var>", low=<var class="term">nn</var>, high=<var class="term">nn</var>===
Explanation: This is a debugging error message.
 
Response: No response is required.
 
Return Codes: I 0 0 AUDITMS
----

===M204.1387: Allocate failed; DDNAME=<var class="term">ddname</var>,DSNAME=<var class="term">dsname</var> could not be located===
Explanation: An attempt to allocate an existing data set, data set name=<var class="term">dsname</var>, failed because the specified dsname was not found in the catalog or the catalog could not be accessed.
M204.1387 replaces M204.1070: ALLOCATE FAILED - <var class="term">reason</var> with additional information regarding the failure of the ALLOCATE command. However, M204.1070 remains in use by Janus/TCPIP for a different purpose.
Response: Correct the data set name or ensure that the data set exists and is cataloged.
Return Codes: C 0 4 AUDITER
----

===M204.1388: CHUNK size exceeds maximum of <var class="term">nnn</var>===
On a DEFINE field command, the chunk size specified is too large.
User response: Specify a chunk size less than or equal to the maximum.
Return codes: C 0 4
----

===M204.1393: CHUNK clause not of format "CHUNK <var class="term">chunkSize</var> FOR <var class="term">chunkTarget</var>"===

'''Explanation:''' On a DEFINE FIELD, the syntax of the CHUNK clause was not in the format shown in this message.
 '''File manager response:''' Correct the DEFINE FIELD command that has the incorrect CHUNK clause syntax.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1394: CHUNK <var class="term">chunkSize</var> value invalid: <var class="term">reason</var>===

'''Explanation:''' On a DEFINE FIELD, the value specified for the size of a CHUNK is invalid;
"reason" indicates why.
 '''File manager response:''' Correct the DEFINE FIELD command that has the invalid CHUNK size.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1395: CHUNK target field invalid type: <var class="term">reason</var>===

'''Explanation:''' On a DEFINE FIELD, the field specified as a CHUNK target is not a field type that can be used as a chunk target, for the reason specified.
 '''File manager response:''' Correct the DEFINE FIELD command containing the invalid CHUNK target type.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1396: CHUNK fields must be INVISIBLE ORDERED NUMERIC===

'''Explanation:''' On a DEFINE FIELD, an attempt was made to create a CHUNK field that was not INVISIBLE ORDERED NUMERIC, which is a requirement of chunk fields.
 '''File manager response:''' Correct the DEFINE FIELD command that has the invalid CHUNK target type.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.1397: A CHUNK field was defined, %F may no longer be opened with M204 releases prior to V7R5===
'''Response:''' This is an informational message. No action is required.
 '''Return Codes:''' I 0 0 AUDITMS

----

===M204.1399: Same server area defined for server above the bar and non swappable server===
Explanation: The same server table has been defined in SERVNSA and SERVGA.
 '''Response:''' Correct the SERVNSA and/or SERVGA settings.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.1400: Server areas ATB require server swapping in memory===
Explanation: Parameters indicated that server areas ATB were used in the run where CCASERVR data set was defined.
 '''System Manager Response:''' Either remove the server areas ATB parameters or use server swapping in memory.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.1402: Invalid value for chunk target: <var class="term">fname</var>='<var class="term">val</var>'; values must be -999999999999999 -> 999999999999999===
Explanation: If a chunk target is any field type besides DATETIME, any value stored in it must be within the range shown in the error message.
 Response: Correct the value being stored.
 System manager response: Correct the value being stored.
 Return Codes: C 0 4 CANCEL


----

===M204.1403: Increase SERVGSZ to at least %C for required ATB server areas===
Explanation: The total size of ATB server areas is larger than the ATB server size defined in SERVGSZ.
 '''User Response:''' If the message is issued by the UTABLE command, decrease the size of the ATB server areas.
 '''System Manager Response:''' If the message is issued at initialization, either increase SERVGSZ or decrease the ATB server area size.
 '''Return Codes:''' E 80 80 AUDITAD OPR

----

===M204.1412: <var class="term">service</var> not allowed with ATB servers===
Explanation: The requested service is not compatible with ATB (above the bar) servers.
 System manager response: Remove the ATB server parameters and restart Model 204.
 Return Codes: E 0 4 AUDITMS

----

===M204.1433: CCAGEN: IS EMPTY ¦ CCAGEN: PERMANENT I/O ERROR===
Explanation: There were no valid records found in the journal(s) pointed to by CCAGEN, or a permanent I/O error was encountered.
 System manager response: Verify that you have the correct journal(s) for the run. If I/O errors were detected while reading in CCAGEN, the appropriate error messages will have been issued before this message. Correct the error and rerun media recovery. If the problem remains unclear, contact Technical Support and have the following documentation available:
<ul><li>Audit trail</li>
<li>Snap dump</li>
<li>UTILJ output for CCAGEN dataset</li></ul>
Return Codes: C 0 4 AUDITER

----

===M204.1489: Not enough file space to continue procedure definition - %F===
Explanation: There is no room in the file to store the procedure being entered with the PROCEDURE command.

<table>
<tr><td>If…</td><td>Then Model 204…</td></tr>
<tr><td>Error occurs after the first line of procedure text has been stored</td><td>Keeps the partial procedure</td></tr>
<tr><td>You are entering the text at your terminal</td><td>Ends procedure definition immediately</td></tr>
<tr><td>Procedure text is supplied by another procedure</td><td>Flushes the remainder of the input</td></tr>
<tr><td>Procedure text is supplied in a batch input stream (CCAIN)</td><td>Flushes the remainder of the procedure text and resumes processing after the END PROCEDURE command</td></tr>
</table>

Response: Create space in the file by deleting unwanted procedures or increasing Table D with the INCREASE command. Replace the partial procedure using the PROCEDURE command, or use the EDIT command to supply the missing text.

Return Codes: C 0 4 CANCEL AUDITER

----
===M204.1508: %<C userid> is not authorized to use Model 204===
Message M204.1508 has been updated to include the actual user ID of the unauthorized user.
Explanation: This user ID does not have the authority to use Model 204. Login authorization to Model 204 is defined by your installation security officer or system manager.

Response: Ask your installation security officer or system manager to authorize you for logging into Model 204.
System manager response: Contact the installation security officer or issue the appropriate external security system commands to give the user’s logon ID the authority to use Model 204. Refer to the [[Security_interfaces_overview|Security interfaces pages]] for instructions.

Return Codes: C 0 4 AUDITER

----

===M204.1587: FSCB full, IMAGE too large: LFSCB required = <var class="term">num</var>, bytes available in FSCB = <var class="term">num</var>===
Explanation: The value specified in an <var>Identify</var> statement with
the <var>Len</var> or <var>Occurs</var> option causes the size of the associated <var>Image</var> to
overflow the full screen buffer (FSCB). The FSCB is a server work area
that is used to hold a compiled Image definition.
'''Response:''' Use the <var>VIEW LFSCB</var> command to determine the current
size of the FSCB. Use the <var>UTABLE</var> command to increase the value of the
<var>LFSCB</var> parameter. Check the <var class="product">SOUL</var> request for programming errors
that might cause the value specified in the <var>Identify</var> statement to be
too large. Retry the request.
'''Return Codes: '''C 0 4 CANCEL AUDITER 

----

===M204.1589: Maximum IMAGE length is 32767: LFSCB required = <var class="term">num</var>===
Explanation: An attempt has been made to define an image greater than 32K.
'''Response:''' Redefine the image so that it is not greater than the maximum length of 32767.
'''Return Codes:''' C 0 4 CANCEL AUDITER

----
===M204.2126: User's pushdown list overflowed===

'''Explanation:''' The user's pushdown list is an internal stack for maintaining state information for user threads across internal Model 204 subroutines. The user pushdown list lives in each user's server. Its size requirement depends on the complexity of the command or User Language request.

This message is issued whenever Model 204 detects that pushdown list data has spilled into adjacent control structures. Because of potential corruption the user is restarted.
 '''Response:''' Increase the size of the user pushdown list by using the LPDLST parameter of the UTABLE command. Notify your system manager.
 '''System Manager Response:''' If this becomes a frequent occurrence, consider more permanent changes to LPDLST and SERVSIZE, since the pushdown list is a server component.
 '''Return Codes:''' C 0 4 CANCEL
----
===M204.2329: <var class="term">subsystem_name</var> at <var class="term">location_name</var> unavailable===
Explanation: The indicated subsystem at the specified node is not available for use due to one or more errors occurring at the specified node during start or login processing.
Response: Notify the system manager or try again later.
System manager response: If the subsystem is started, stop the subsystem and resolve communications errors or other errors which occurred at the specified node. After resolving error, use the START SUBSYSTEM command to make the subsystem available for general use. Check to make sure that the LOCATION parameter was set properly in the CCAIN input stream for the Online.
Return Codes: C 0 4
----

===M204.2551: {FPL|FCT PG1} is invalid for file: <var class="term">filename</var>===

'''Explanation:''' If the message says FPL, then the FPL (file parameter list) for the associated file is invalid. This could be the result of an incorrect DD, FILEDEF or DLBL statement.

If the message says FCT PG1, then the existence page array page is invalid.

'''File manager response:''' If the DD, FILEDEF or DLBL statement is correct and points to the correct data set, then the file must be restored from a backup.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.2651: Not all threads processed for IODEV %C===
Explanation: The run is terminated because either:
<ul>
<li>The number of threads specified by NUSERS has been initialized, but there are fewer users of the specified IODEV type than expected.</li>
<li>The DUPTERM number specified by the IODEV card could not be initialized because it exceeded the number of NUSERS.</li>
</ul>
Response: Check that NUSERS matches the total of the listed IODEVs, plus one extra for USER 0. Check also the NOTERM/DUPTERM parameter for the specified IODEV card.
Return Codes: E 80 80 ER
----
===M204.2719: Open %C failed. Update statements already compiled, read only privileges insufficient===
Explanation: The OPEN or OPENC User Language statement was issued from a request to reopen a file with read-only privileges. However, that request had already been compiled with update statements against the file.
Response: In a User Language request, you cannot use the User Language OPEN or OPENC statement to reopen a file with read-only privileges, if that request contains updates statements against the same file.
Descriptor code: C 0 4 CANCEL
----
===M204.2739: Parameter <var class="term">parm</var> cannot be reset on user 0’s parameter line: value ignored===
Explanation: You reset parameter <var class="term">parm</var> on the User 0 parameter line, but the parameter cannot be set there. The value is ignored, the default value for this parameter remains in effect.
Response: Remove <var class="term">parm</var> from the User 0 parameters, since it will not change the value of the parameter.
Descriptor code: E 0 4 AD
----
===M204.2746: XSIZE*XRECPPG may not be 1 nor exceed 536870911===
Explanation: The product of XSIZE and XRECPPG must not exceed 16777216 times 32 minus one, or 536870911. This specifies the maximum number of extension records allowed in a single Model 204 file when using Table X. Also, setting both XRECPPG and XSIZE to 1 is invalid.
The CREATE command is rejected.
Response: Retry the command specifying values for XSIZE and XRECPPG whose product does not exceed the 526870911 limit. Refer to the <var class="book">Rocket Model 204 File Manager’s Guide </var>for more information on file sizes.
Descriptor code: C 0 4
----

===M204.2774: Another command command is in progress===

Explanation: An INCREASE or DECREASE command or auto increase is taking place while another INCREASE, DECREASE, or auto increase has not finished yet.
 File manager response: Repeat the command after the completion of the auto increase or previous INCREASE or DECREASE command.
 Descriptor code: C 0 4

----

===M204.2826: %F %C compaction not allowed===

'''Explanation:''' An attempt was made to compact a file created prior to Model 204 version 6.3.
 '''File manager response:''' Reorganize the file using Model 204 version 6.3.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2831: Updates to DTS files not supported in this environment===
Explanation: DTS files cannot be updated in IFAM, SQL, or PQO environments.
Response: Do not attempt to update DTS file.
Return Codes: C 0 4
----
===M204.2833: Fields cannot be defined in a file with ATRPG*ASTRPPG>4000===
Return Codes: C 0 4
----
===M204.2836: Value of parameter %C invalid—reset to %C===

'''Explanation:''' This is an informational message only.

A parameter was specified with an incorrect value. It has been reset to an internally calculated value that will accommodate other parameter settings. See the description of the parameter named to see what that calculation involves.
 '''System Manager Response:''' The parameter has been reset. No response is required.
 '''Return Codes:''' I 0 0 AUDITMS
----

===M204.2838: %C only valid in FILEORG X’100’ files===
Return Codes: C 0 4
----
===M204.2839: %C is a %C, not a %C===
Return Codes: C 0 4 ECHO
----
===M204.2841: Remote fieldgroups not supported===
Return Codes: C 0 4 ECHO
----
===M204.2842: Invalid context for fieldgroup===
Return Codes: C 0 4 ECHO
----
===M204.2843: Maximum fieldgroup id exceeded in record %R in %F===
Return Codes: C 0 4 CANCEL
----
===M204.2844: Mix of fields and fieldgroups, name <nowiki>=</nowiki>===
Return Codes: C 0 4 SUFFIX ECHO
----

===M204.2845: Invalid fieldgroup context for %C===
Explanation: The $function was used outside of field group context.
Descriptor code:C 0 4 SUFFIX ECHO
----
===M204.2846: Invalid fieldgroup context for %C===
Return Codes: C 0 4 CANCEL
----
===M204.2847: Fieldgroup context lost in record %R in %F===
Return Codes: C 0 4 CANCEL
----
===M204.2848: Invalid fieldgroup id: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2849: Required keyword %C missing===
Return Codes: X 0 4 ECHO
----

===M204.2850: %C value missing===
Return Codes: C 0 4
----
===M204.2851: %C value "%C" too big, must be <%C bytes===
Return Codes: C 0 4
----

===M204.2852: Update to missing fieldgroup occurrence in record %R in %F===
Return Codes: C 0 4 CANCEL
----

===M204.2853: %C not allowed for EXACTLY-ONE field===
Return Codes: C 0 4
----

===M204.2854: Attempt to do %C for EXACTLY-ONE field: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2855: Field depth+length unrepresentable in record %R in %F===
Return Codes: C 0 4 CANCEL
----

===M204.2856: Fieldname variable %C: expected %C, got %C===
Return Codes: C 0 4 CANCEL
----

===M204.2857: %C field not allowed for %C field===
Return Codes: C 0 4
----

===M204.2858: Fieldgroup context mismatch between COUNT-OCCURRENCES-OF field and counted field===
Return Codes: C 0 4
----

===M204.2859: New automatic field not allowed for non-empty file===
Return Codes: C 0 4
----

===M204.2860: Field %C already has a COUNT-OCCURRENCES-OF field===
Return Codes: C 0 4
----

===M204.2861: Occurrence counter %C overflowed===
Return Codes: C 0 4 CANCEL
----

===M204.2862: Attempt to update automatic field %C===
Return Codes: C 0 4 SUFFIX ECHO
----

===M204.2863: Attempt to do %C for automatic field: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2865: Attempt to %C invalid datetime value: %C = %C===
Return Codes: C 0 4 CANCEL
----

===M204.2866: File already has %C field===
Return Codes: C 0 4
----

===M204.2867: Fieldgroup %C already has %C field===
Explanation: If you try to define a second update tracker field of the same type for the same field group, you will invoke message 2867, where %C represents:
<ul>
<li>A CREATE-TIME</li>
<li>A CREATE-TIMEUTC</li>
<li>A CREATE-USER</li>
<li>AN UPDATE-TIME</li>
<li>AN UPDATE-TIMEUTC</li>
<li>AN UPDATE-USER</li>
</ul>
Return Codes: C O 4
----

===M204.2868: MINLOBE must be between 0 and %C===
Return Codes: C 0 4
----

===M204.2869: Change refused: MINLOBE > 0 for File <var class="term">filename</var> field <var class="term">fieldname</var>===
'''Return Codes:''' C 0 4 AUDITER
----

===M204.2870: Change refused: MINLOBE > 0 for <var class="term">filename</var> field <var class="term">fieldname</var>===
'''Return Codes:''' C 0 4 CANCEL AUDITER
----

===M204.2871: Fieldgroup context mismatch between CONCATENATION-OF field and COMPONENT field===
Return Codes: C 0 4
----

===M204.2872: Concatenation value too long for field %C===
Return Codes: C 0 4 CANCEL
----

===M204.2873: Concatenation field %C component field %C contains separator character===
Return Codes: C 0 4 CANCEL
----

===M204.2874: Attempt to %C a value that's %C: %C===
Return Codes: C 0 4 CANCEL
----

===M204.2875: Concatenation list invalid: %C===
Return Codes: C 0 4
----

===M204.2876: Invalid %C value: %C===
Return Codes: C 0 4
----

===M204.2877: WITH clause invalid: %C===
Return Codes: C 0 4 ECHO

----

===M204.2878: WITH clause invalid: field %C in %F %C===
Return Codes: C 0 4 CANCEL
----

===M204.2879: Remote id %C mode %C===
Return Codes: I 0 0 SAVE NOTERM OPR

----

===M204.2880: Memory datasets cannot be part of multi-dataset file===
Return Codes: C 0 4

----

===M204.2881: Data conversion error===
Return Codes: C 0 4 CANCEL

----

===M204.2882: Recovery journal (CCARF) version %C is not supported===
Explanation: A CCARF data set was provided as input to a recovery step, but that CCARF data set was produced by a different version of Model 204 than the version that is running recovery.
 System manager response: Correct the data set name referenced in CCARF and ensure that it was produced by the version of Model 204 that you are using to run recovery.
 Return codes: E 52 52 OPR

----

===M204.2883: Mix of journal versions in recovery CCARF===
Return codes: E 52 52 SNAP OPR

----

===M204.2884: {Field|Fieldgroup} was previously defined as a {fieldgroup|field}, new definition ignored===
Return Codes: C 0 4

----

===M204.2885: Invalid fieldgroup id: <var class="term">fieldgroup</var>===
Return Codes: C 0 4 CANCEL

----

===M204.2886: Fieldgroup id %C already exists in record %R in %F===
Return Codes: C 0 4

----

===M204.2903: FILEORG=X'100' is not supported during FLOD/FILELOAD===
Return Codes: E 0 8
----

===M204.2916: %C requires at least one area to be set in %C===
'''Explanation:''' When the size of a non-swappable server area is indicated (SERVNSSZ), at least one non-swappable server area must be indicated in SERVNSA.
 '''Operator response:''' Correct the SERVNSA parameter setting.
 '''Return Codes:''' E 0 4 AUDITMS
----

===M204.2921: Server areas above the bar are not supported in VSE===
'''Explanation:''' Non-swappable server areas ATB are not supported in VSE.
 '''Operator response:''' Remove the parameters for non-swappable server areas.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.2922: %C bit setting is not valid===
'''Explanation:''' The bit setting in [[SERVNSA parameter|SERVNSA]] is not valid.
 For release 7.4, valid bits are: X'02000000'
 For release 7.5, valid bits are: X'02000000', X'00800000', X'00004000', and X'00002000'
 '''Operator response:''' Correct the SERVNSA setting.
 '''Return Codes:''' E 0 4 AUDITMS
----

===M204.2933: Module version mismatch, KOMM=%C, %C=% C===
'''Return Codes:''' E 0 4 SNAP

----
===M204.2934: FILEORG X<nowiki>'200'</nowiki> not supported for hashed or sorted file organizations===
'''Explanation:''' Hashed or sorted files must be 16M files. The CREATE FILE command
is rejected.
 '''File manager response:''' Remove the conflicting FILEORG parameter and reissue CREATE FILE.
 '''Return Codes:''' E 0 4 AUDITMS

----

===M204.2935: {CHUNK|CHUNK target} fields may not be RENAMED or DELETED===
'''File manager response:''' Do not attempt to RENAME or DELETE chunks or chunk targets.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2936: A CHUNK field of size <var class="term">nnn</var> already exists for this field===
'''Explanation:''' For a given CHUNK target field, duplicate chunk sizes are not permitted.
 '''File manager response:''' Correct the DEFINE FIELD that caused the message.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2937: CHUNK SIZE: <var class="term">nnn</var> is not an integral multiple/divisor of the existing CHUNK size: <var class="term">nnn</var>===
'''Explanation:''' A CHUNK field's chunk size must be an integral multiple/divisor of all other chunk's sizes for a given chunk target.
 This message identifies the existing chunk size that conflicts with the new one.
 '''File manager response:''' Correct the DEFINE FIELD that caused the message.
 '''Return Codes:''' C 0 4 AUDITER

----

===M204.2938: You may not define more than %C chunks for a field===
'''Explanation:''' A given chunk target can have at most 20 chunks defined.
 '''File manager response:''' Do not try to define more than 20 CHUNK fields for any given CHUNK target field.
 '''Return Codes:''' C 0 4 AUDITER
----

===M204.2939: %C has been set to its %C value: %C===
'''Explanation:''' TBD
 '''Return codes:''' I 0 0 AUDITMS

----

===M204.2940: Use of filename after INITIALIZE keyword discouraged because it gave different results prior to version 7.5===
'''Explanation:''' This message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if it was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
 
If you have entered the name of the file being initialized AFTER the INITIALIZE command keyword, you can either correct the command (that is, remove the filename after the INITIALIZE command keyword) or use the MSGCTL M204.2940 command as described below so that the command can continue to work.
 '''File manager response:''' The most direct response is to correct the command to conform to the proper syntax, that is, remove extraneous strings after the INITIALIZE command keyword.
 '''System manager response:''' If the file manager has chosen to keep the filename after the INITIALIZE command keyword, and the filename is the same as the name of the file being initialized, you can have the following command executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2940 NOCOUNT
This action represents a very special case for the NOCOUNT option of MSGCTL.
 
Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.
 
For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 
Issuing the above MSGCTL command with version 7.5 of Model 204 will not present any risk of an incorrect operation of INITIALIZE.
A word of caution, however: In prior versions of Model 204, a filename after the INITIALIZE command keyword is NOT checked against the name of the file being initialized. Therefore the use of the filename after the INITIALIZE command keyword could be a risky practice if such a command might be used in a prior version of Model 204.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2941: File being initialized does not match name given after INITIALIZE command: %C===
'''Explanation:'''
This message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if it was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
 
In some cases, users have entered the name of the file being initialized AFTER the INITIALIZE command keyword, but this message indicates that whatever string you entered after the INITIALIZE command keyword is not the name of the file being initialized.
 '''File manager response: '''
Correct the command. The most direct response is to correct the command to conform to the proper syntax: that is, remove extraneous strings after the INITIALIZE command keyword.
 
However, if the system manager has performed a MSGCTL M204.2940 NOCOUNT command, and you want to enter the correct filename on the INITIALIZE command, that will allow the INITIALIZE operation to proceed.
 
'''System manager response: '''
 If the file manager is unable to correct the INITIALIZE command, you can have the following commands executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2940 NOCOUNT
MSGCTL M204.2941 NOCOUNT
These actions represent a very special case for the NOCOUNT option of MSGCTL.
 Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but it does not directly affect the operation which issued the error message.
 For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 Issuing MSGCTL M204.2941 NOCOUNT is not recommended, because this results in what might appear to be checking of the filename when in fact it is not checked.
 Issuing MSGCTL M204.2940 NOCOUNT does not present any risk with version 7.5 of Model 204, but, as discussed in the System Manager response section of message 2940, this practice should be done with caution.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2942: Extraneous string after field attribute list: %C===
'''Explanation:''' This message indicates that the format of the INITIALIZE command as entered for a hashed, sorted, or record security file does not conform to the syntax of:
INITIALIZE
[SORT fldName (attributes)]
[HASH fldName (attributes)]
[RECSCTY fldName (attributes)]
In particular, it indicates that some string followed the right parenthesis (')') of the attribute list.
Prior to version 7.5, nothing after the closing parenthesis was checked.
 '''File manager response:''' Correct the command. There should be no string after the right parenthesis.
 '''System manager response:''' If the file manager is unable to correct the INITIALIZE command, you can have the following command executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2942 NOCOUNT 
This action represents a very special case for the NOCOUNT option of MSGCTL. Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.
 For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 Issuing MSGCTL M204.2942 NOCOUNT is not recommended, because if you issue this command the string after the right parenthesis will not be analyzed.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2943: Error using filename phrase for file %C: <var class="term">restriction</var>===
'''Explanation:''' This message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if it was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
 
In some cases, users have entered the name of the file being initialized AFTER the INITIALIZE command keyword, but this message indicates that the syntax requires some modification for the particular file being initialized.
 '''File manager response:''' The command should be corrected; the most direct response is to correct the command to conform to the proper syntax, that is remove extraneous strings after the INITIALIZE command keyword.
However, if the system manager has performed a MSGCTL M204.2940 NOCOUNT command, you can modify the command as indicated by the <var class="term">restriction</var> shown in the M204.2943 text.
 '''System manager response:''' If the file manager is unable to correct the INITIALIZE command, you can have the following commands executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2940 NOCOUNT
MSGCTL M204.2943 NOCOUNT
This action represents a very special case for the NOCOUNT option of MSGCTL. Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.
 
For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.
 
Issuing MSGCTL M204.2943 NOCOUNT is not recommended, because this bypasses the checking that is intended by the <var class="term">restriction</var> shown in the M204.2943 text.
 
Issuing MSGCTL M204.2940 NOCOUNT does not present any risk with version 7.5 of Model 204, but, as discussed in the system manager response for M204.2940, this practice should be done with caution.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2944: Should have end of <var class="term">cmd</var> command but instead found: <var class="term">string</var>===
'''Explanation:''' This message indicates that the format of the command indicated by cmd as entered does not conform to command syntax.
 '''User response:''' Correct the command, either by simply removing string and any following strings or else by correcting the command to conform to the proper syntax.
 '''File manager response:''' If the cmd in the M204.2944 text is INITIALIZE, this message indicates that the format of the INITIALIZE command as entered does not conform to the syntax of:
INITIALIZE [KEEPDEF[S]]
Prior to version 7.5, it was possible to place any text on the INITIALIZE command, and if the text was anything other than KEEPDEF[S], it was ignored. In version 7.5, the syntax of INITIALIZE command is checked for strict correctness.
The command should be corrected as described in the user response above.
 '''System manager response:''' If the file manager is unable to correct the INITIALIZE command, you can have the following command executed at any time before the INITIALIZE command is executed:
MSGCTL M204.2944 NOCOUNT
This action represents a very special case for the NOCOUNT option of MSGCTL. Normally, the NOCOUNT option only changes a message such that it does not increment the count of counting errors, but does not directly affect the operation which issued the error message.

For this message, however, setting the NOCOUNT operation indicates that this condition is to be allowed, and normal processing of the INITIALIZE command will continue.

Issuing MSGCTL M204.2944 NOCOUNT is not recommended, because whatever string was indicated on the INITIALIZE command is not checked.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2945: Error encountered, <var class="term">cmd</var> command not performed===
'''Explanation:''' This counting error message indicates that the processing of the <var class="term">cmd</var> command was not performed. This message should be preceded by one or more messages. (If the preceding messages were not counting error messages, they might not have been displayed on the user's terminal, depending on the MSGCTL parameter setting.)
 '''User response:''' Correct any conditions indicated by the preceding messages.
 '''Return codes:''' C 0 4 AUDITER

----

===M204.2946: Error encountered, <var class="term">cmd</var> command not performed ===
'''Explanation:''' This informational message indicates that the processing of the <var class="term">cmd</var> command was not performed. This message should be preceded by one or more messages. (If the preceding messages were not counting error messages, they might not have been displayed on the user's terminal, depending on the MSGCTL parameter setting.)
 '''User response:''' Correct any conditions indicated by the preceding messages.
 '''Return codes:''' I 0 0 AUDITMS

----

===M204.2947: Module address <var class="term">address</var> length <var class="term">length</var> protected===
Explanation: This informational message is displayed during startup to show the ranges of load module protection. To see which Rocket CSECTs are being referenced, look at the module map in a snap. For more information on the load module protection facility, see the [[MODPROT parameter]] description.
 Response: No response is required.
 Return codes: I 0 0 AUDITMS

==DDGEN messages==
===DDG017: UNABLE TO PROCESS NON-TBO FILE WITH SYSOPT=4, CHANGE FILE TO TBO OR RESET SYSOPT.===
===DDG018: FICREATE UNRECOGNIZABLE. DDGEN RUN CANCELLED.===

[[#toc|Up to Contents]]

[[Category:Release notes]]

File Load utility: FLOD and FILELOAD commands

2015-07-27T23:45:43Z

Tbullock: Clone text about FILEORG x'100' from the FILEORG_parameter page

<div class="toclimit-3">

The <var>FLOD</var> or <var>FILELOAD</var> command is followed by a series of file load statements that comprise the file load program. The program is terminated by an <var>END</var> statement, beginning in column 1.
<ul>
<li>If you are doing a multistep File Load procedure, the <var>FLOD</var> command
marks the beginning of a file load program.</li>
<li>If you are doing a one-step procedure, use the <var>FILELOAD</var> command.</li>
</ul>


<var>FILEORG</var> X'100' files cannot be loaded via <var>[[FLOD_command|FLOD]]</var> or
<var>[[FILELOAD_command|FILELOAD]]</var> except with a <var class="product">
[[Media:FrelrNew.pdf|Fast/Reload]]</var> <var>Load All Information</var> (<var>LAI</var>)
<var>FLOD/FILELOAD</var> program.


These commands place the file in deferred update mode, in which updates to Tables C and D are deferred to deferred update data sets and are applied later to Tables C and D.

===Including the FLOD or FILELOAD command in your run===

Include the <var>FLOD</var> or <var>FILELOAD</var> command and its associated file load program in the CCAIN data set, along with any other <var class="product">Model 204</var> commands needed to prepare the file for loading or to manipulate or check the data after loading.
Note:
There can be only one <var>FLOD</var>, <var>FILELOAD</var>, or <var>Z</var> command specified in any given File Load job step. 

===Getting information about a FLOD or FILELOAD run===

Some of the characteristics of the File Load run such as the number of records deleted or the number of fields added during the run are kept as counters that are printed at the end of the run. These counters are listed in [[#FLOD and FILELOAD command output|FLOD and FILELOAD command output]]. A histogram listing the distribution of deferred update record lengths along with the number of records for each range of lengths is also displayed for variable-length deferred update data sets. It can be used as an aid to setting the variable-length sort parameter, and is illustrated in [[Deferred update feature#Setting the variable-length parameter(vl)|Setting the variable-length parameter(vl)]]. 

==Double-checking your file load run==

If you know how many records you are loading, you can use the SOUL <var>FPC</var> (Find and Print Count) construct to ensure that all records have been loaded.

===Loading nondeferrable fields===

If you are loading fields whose updates should not be deferred, it is not sufficient to specify the <var>NON-DEFERRABLE</var> attribute in order to override the deferral of updates for these fields. (In single-user File Load runs, the <var>NON-DEFERRABLE</var> attribute is ignored by <var class="product">Model 204</var>.) See [[Deferred update feature#Overriding deferred updates|Overriding deferred updates]] for a description of the techniques available to override deferred updates.

===Do not use RRN files in deferred update mode===

Rocket Software suggests that you do not use deferred update mode with <var>Reuse Record Number</var> files except where you are performing simple record adds (such as reorganizing files). Doing so could cause you to lose updates without warning. See [[File design#RRN files and deferred update_mode|RRN files and deferred update mode]] for more information.

==FLOD command==

The <var>FLOD</var> command marks the beginning of a file load program. This command is followed by the file load statements described starting on [[#File Load statements: overview|File Load statements: overview]]. The procedure ends with the word <var>END</var>, beginning in column 1.

===Syntax===

The format of the <var>FLOD</var> command is:

FLOD k,n,m
.
.
.
END


Where: 
<ul>
<li><var class="term">k</var> specifies the maximum number of records to be loaded into the <var class="product">Model 204</var> file:
<ul>
<li>If <var class="term">k</var> is -1, <var>FLOD</var> loads all records into the <var class="product">Model 204</var> file.</li>

<li>If <var class="term">k</var> is any negative number except -1, the number is converted into a 32-bit unsigned number, <var>N,</var> and <var>N</var> records are processed. </li>
</ul></li>

<li><var class="term">n</var> specifies the maximum number of times the statements in the file load program are to be executed:
<ul>
<li>If <var class="term">n</var> is 0, the <var>FLOD</var> or <var>FILELOAD</var> code is compiled, but is <var class="term">not</var> executed. </li>

<li>If <var class="term">n</var> is -1, <var>FLOD</var> keeps making passes through the code until the process is stopped by another condition (such as EOF)</li>
</ul></li>

<li><var class="term">m</var> specifies the number of input records to skip before starting the File Load process, which is helpful for breaking up the load process so that dumps (backups) can be taken during large loads:
<ul>
<li>If <var class="term">m</var> is -1, all records are skipped.</li>

<li>If <var class="term">m</var> is any negative number except -1, the number is converted into a 32-bit unsigned number, <code>N</code>, and <var>FLOD</var> skips <code>N</code> records before processing begins.</li>
</ul></li>
</ul>

===Usage===

Each time the <var>END</var> statement is encountered during execution, <var class="product">Model 204</var> begins again with the first statement following the <var>FLOD</var> command. The procedure continues to execute until one of the following occurs:
<ul>
<li>All the records in the input data set have been processed.</li>
<li><var class="term">k</var> records have been added to the <var class="product">Model 204</var> file.</li>
<li><var class="term">n</var> passes have been made through the file load program. </li>
</ul>

Thus, either <var class="term">k</var> or <var class="term">n</var> can be used to limit File Load processing and to load only a sample of the data. 

To process all the input records, set both <var class="term">k</var> and <var class="term">n</var> to -1. 

====Example====

The following command specifies that all input records be processed starting with the first record (that is, skip 0 records):
FLOD -1,-1, 0


==FILELOAD command==

To perform a one-step file load, use the <var>FILELOAD</var> command to mark the beginning of a file load program. This command is followed by the file load statements described starting on [[#File Load statements: overview|File Load statements: overview]]. The procedure ends with the word <var>END</var>, beginning in column 1.

===FILELOAD command processing===

The <var>FILELOAD</var> command attaches one or two sort subtasks to do the sorting required to load index and <var>FRV</var> entries efficiently. These subtasks run asynchronously with <var class="product">Model 204</var> (except under z/VM, which does not support true subtasking). Two buffers are used for the sorts. <var class="product">Model 204</var> fills the second buffer while the sort is emptying the first. After the records are sorted, the same double-buffering mechanism is used to pass the records back to <var class="product">Model 204</var>.

====Syntax====

The complete format of the <var>FILELOAD</var> command is:

FILELOAD k,n,m [,[s1] [,[s2] [,[s3] [,[s4] [,vl]]]]]
.
.
.
END


Where:
<ul>
<li><var class="term">k</var>, <var class="term">n</var>, and <var class="term">m</var> have the meanings described for the <var>FLOD</var> command in [[#FLOD command|FLOD command]], above.</li>

<li><var class="term">s1</var> represents the amount of memory that the sort package uses for sorting the deferred update index records produced by the file load program. If <var class="term">s1</var> is omitted or is not a positive integer, a default value of 50,000 bytes (64K for z/VM) is used for the sort work space.

Note: Make the <var class="term">s1</var> parameter as large as possible, especially for sorts involving many records. It is important to increase <var class="term">s1</var> for large sorts. </li>

<li><var class="term">s2</var> represents the amount of memory used for sorting the deferred update <var>FRV</var> index records. If <var class="term">s2</var> is omitted or is not a positive integer, a default value of 50,000 bytes (64K for z/VM) is used. For 3380 disk drives the minimum values for <var class="term">s1</var> and <var class="term">s2</var> are 64,000 bytes.</li>

<li><var class="term">s3</var> represents the amount of memory allocated for the two buffers used to pass data from <var class="product">Model 204</var> to the sorts. This parameter specifies the combined size of the two buffers. The core specified in <var class="term">s3</var> is evenly divided between the two buffers, and the default value of <var class="term">s3</var> is 8000 bytes. The minimum value accepted is 48 bytes, but such a small size is not recommended. A larger value of <var class="term">s3</var> can produce a noticeable performance improvement. However, increasing <var class="term">s1</var> normally has a greater effect on performance than a corresponding increase in <var class="term">s3</var>.</li>

<li><var class="term">s4</var> represents the amount of memory allocated for the two buffers used to pass data from the sorts to <var class="product">Model 204</var>. <var class="term">s4</var> is ordinarily equal in size to <var class="term">s3</var> and is set equal to <var class="term">s3</var> by default.</li>

<li><var class="term">vl</var> specifies the maximum sort record length in variable-length record sorts. (<var class="term">vl</var> corresponds to the <var>L2</var> of the <var>RECORD</var> sort statement.)

The <var class="term">vl</var> parameter is required when <var>ORDERED</var> fields are updated by the file load program. For efficiency, do not use the <var class="term">vl</var> parameter if <var>ORDERED</var> fields are not updated. For more information about the <var class="term">vl</var> parameter and how to select a value for it, see [[Deferred update feature#Setting the variable-length parameter(vl)|Setting the variable-length parameter(vl)]]. </li>
</ul>

====Examples====

To specify a value for <var class="term">s2</var>, but not <var class="term">s1</var>, supply two consecutive commas before <var class="term">s2</var>, as follows:
FILELOAD <var class="term">k,n,m,,s2,s3,s4</var>


The same technique can be used to specify values for <var class="term">s3</var>, <var class="term">s4</var>, and <var class="term">vl</var>. For example:
FILELOAD <var class="term">k,n,m,,,,,vl</var>


Alternatively, specify a zero or negative value for <var class="term">s1</var> and allow the system to supply the default. The same technique can be used to specify values for <var class="term">s2</var>, <var class="term">s3</var>, and <var class="term">s4</var>. For example:
FILELOAD <var class="term">k,n,m,</var>0,-1,-2,-3,<var class="term">vl</var>


===FILELOAD error reporting===

If a serious problem arises while the <var>FILELOAD</var> command is running, the user is restarted. A message is issued reporting the completion codes issued by the sorts. The message is:
*** M204.0760: SORT RETURN CODES - SORT 1: <var class="term">xxxxxx</var>,
SORT 2: <var class="term">xxxxxx</var>


The completion codes issued by the sorts (<var class="term">xxxxxx</var>) are reported as six hexadecimal digits. The first three digits are the subtask system completion code, such as <code>0C4</code>. The last three digits are the user completion code, such as <code>010</code> (which is a decimal 16). These completion codes can be useful in determining whether a problem is in <var class="product">Model 204</var> or is in the sort package itself.

==FLOD and FILELOAD command output==

After the file load program has completed, the following counters are displayed: 
<table>
<tr class="head">
<th>This counter </th>
<th>Displays the number of... </th>
</tr>

<tr>
<td>RECORDS INPUT </td>
<td>Records read from the TAPEI (input) data set, including those skipped by the <var>FLOD</var> or <var>FILELOAD</var> command</td>
</tr>

<tr>
<td>ADDS </td>
<td>New <var class="product">Model 204</var> records begun</td>
</tr>

<tr>
<td>DELETES </td>
<td><var class="product">Model 204</var> records deleted</td>
</tr>

<tr>
<td>AF </td>
<td>Fields added</td>
</tr>

<tr>
<td>DF </td>
<td>Fields deleted (not including those deleted through a <var>DELETE</var> command) </td>
</tr>
</table>

These counters can help you ensure that you have added, deleted, or changed all the records that you intended to. 

==File Load statements: overview==

<var class="product">Model 204</var> provides several File Load statements that are elements of a separate File Load language.

The file load language provides limited programming capability. If complicated edits or large amounts of data manipulation are required, consider using <var>FLOD</var> exits, a preprocessing program, or a host language or SOUL program to load the file. 

All File Load statements follow the <var>FILELOAD</var> command.

See the following sections for details:
<ul>
<li>[[#File Load statements: mode bits|File Load statements: mode bits]]</li>
<li>[[#File Load statements: loading a new Model 204 file|File Load statements: loading a new Model 204 file]]</li>
<li>[[#File Load statements: manipulating data areas with string buffers|File Load statements: manipulating data areas with string buffers]]</li>
<li>[[#File Load statements: working with index registers|File Load statements: working with index registers]]</li>
<li>[[#File Load statements: updating existing Model 204 records|File Load statements: updating existing Model 204 records]]</li>
<li>[[#File Load statements: deleting records and fields|File Load statements: deleting records and fields]]</li>
</ul>

===File Load statement summary===

See [[#Syntax of File Load statements|Syntax of File Load statements]] for a complete summary of all statements in the File Load language.

==File Load statements: mode bits==

Many of the statements described in the next sections use mode bits. These mode bits allow you to specify various options that are discussed here. Most options can be summed.
Note:
If numeric sequence numbers are present, you must specify mode bits.

===Mode bits summary===
<table>
<tr class="head">
<th>Mode bit </th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">X'8000'</td>
<td>Begin a new <var class="product">Model 204</var> record.</td>
</tr>

<tr>
<td align="right">X'4000'</td>
<td>Delete a field</td>
</tr>

<tr>
<td align="right">X'2000'</td>
<td>Sort or hash key omitted (specified with X'8000')</td>
</tr>

<tr>
<td align="right">X'1000'</td>
<td>Delete first occurrence of field</td>
</tr>

<tr>
<td align="right">X'0800'</td>
<td>Suppress deletion of blanks</td>
</tr>

<tr>
<td align="right">X'0400'</td>
<td>Translate numeric codes</td>
</tr>

<tr>
<td align="right">X'0200'</td>
<td>Load all-zero fields as '0'</td>
</tr>

<tr>
<td align="right">X'0100'</td>
<td>Strip leading zeroes</td>
</tr>

<tr>
<td align="right">X'0080'</td>
<td>Read and load floating point data</td>
</tr>
</table>

===Begin a new Model 204 record (X'8000')===

Mode bit X'8000' causes a new <var class="product">Model 204</var> record to be started. More than one <var class="product">Model 204</var> record can begin on each pass through a file load program. 

For example, suppose that the input statements for the following example each contained data for two people, with one person's data starting in column 1 and the other's in column 41. The file load program might look like this:
FLOD 5000,5000,0
G
SOC.SEC.NO=1,9,X'8000' * begin a new record
NAME=10,14
DEPT=24,2
SCALE=26,6
SOC.SEC.NO=41,9,X'8000' * begin a new record
NAME=50,14
DEPT=64,2
SCALE=66,6
END


The X'8000' mode bit begins a new record even if the field turns out to be all blank, and is not actually stored in the new record (that is, it is possible to have a <var class="product">Model 204</var> record that has no fields).

===Delete a field (X'4000')===

The X'4000' mode bit deletes one field. It is used in conjunction with the read-and-load-a-field statement, as follows:
<var class="term">fieldname</var>=<var class="term">position</var>,<var class="term">length</var>,X'4000'


For more information see [[#File Load statements: deleting records and fields|File Load statements: deleting records and fields]].

===Sort or hash key omitted (X'2000')===

The X'2000' mode bit allows you to specify that a record in a sort or hash key file does not have a sort or hash key. This mode bit can be used in conjunction with the X'8000' mode bit when reorganizing sort or hash key files. For more information, see [[File reorganization and table compaction#Reorganizing sorted and hash key files|Reorganizing sorted and hash key files]].

===Delete first occurrence of field (X'1000')===

The X'1000' mode bit, when combined with the X'4000' and X'0800' mode bits, allows you to delete a specific value from a record. Use the X'4000' mode bit to delete <var>INVISIBLE</var> or <var>VISIBLE</var> fields; the value of the <var>INVISIBLE</var> field must be specified. Use the combined mode bit X'5800' to delete specific values in multiply occurring visible fields. See [[#Deleting a VISIBLE field|Deleting a VISIBLE field]] and [[#Deleting specific values|Deleting specific values]] for more information.

===Suppress blank deletion (X'0800')===

Unless suppressed with mode bit X'0800', the File Load utility automatically deletes leading and trailing blanks from the value string. 

===Translate numeric codes (X'0400')===

Input data sometimes contains information in a coded format. For instance, in the example at the beginning of the section, the department field is expressed as a two-digit code to save space on the input line. The File Load utility can store this code as is. However, if the code is a simple numeric code ranging upwards from 0, you can provide a translation table, using mode bit X'0400', following the read-and-load-a-field statement to convert these codes into full departmental names. 

The following sample statement translates and stores a department code:
DEPT=24,2,X'0400'
= * Code 0
ACCOUNTING= * Code 1
PERSONNEL= * Code 2
PURCHASING= * Code 3
DATA PROCESSING= * Code 4
= * Code 5
MEN'S CLOTHING= * Code 6
WOMEN'S CLOTHING= * Code 7
NOTIONS=
SPORTSWEAR=
MILLINERY=
ADMINISTRATIVE=
.


An input line having '06' in columns 24 and 25 causes the field <code>DEPT=MEN'S CLOTHING</code> to be stored in the new record.

====Creating translation tables====

To create a translation table:
<ol>
<li>Specify mode bit X'0400' on the read-and-load-a-field statement.</li>

<li>Enter the value strings for codes 0 through <var class="term">n</var> on the next <var class="term">n</var>+1 lines, each starting in column 2 and immediately followed by an equal sign (<tt>=</tt>). If a particular code is not used, represent it with a line having only an equal sign in column 2 (like codes 00 and 05 in the above example).</li>

<li>Signal the end of the translation table with a line that contains a period in column 1. </li>
</ol>

====Rules for translation tables====

The code in the data area of the input record must be an EBCDIC character representation of a decimal number. A plus sign (<tt>+</tt>) is permitted; blanks are not.

Translation does not occur and the code itself is stored as the field value in the current <var class="product">Model 204</var> record under the following circumstances: 
<ul>
<li>Data area does not contain a correct positive numeric code.</li>
<li>Code is larger than the translation table.</li>
<li>Code corresponds to a line for which no value is specified.</li>
</ul>
Note:
Do not confuse numeric codes in the input data with the <var>CODED</var> field type option of <var class="product">Model 204</var> files. <var>CODED</var> fields affect only the internal storage of the field value and are virtually transparent to the end-user.

====Using multiple translation table entries on a single line====
Yo
u can place more than one translation table entry on a single line using the following rules:
<ul>
<li>Value for one entry must immediately follow the equal sign for the preceding entry. </li>
<li>Last entry on each line must end with an equal sign. </li>
<li>Entries are numbered just as if each entry appeared on a line by itself. </li>
<li>Period ending the table must always appear on a line by itself.</li>
</ul>

The previous example can be written:
DEPT=24,2,X'0400'
=ACCOUNTING=PERSONNEL=PURCHASING=
DATA PROCESSING==MEN'S CLOTHING=
WOMEN'S CLOTHING=NOTIONS=SPORTSWEAR=
MILLINERY=ADMINISTRATIVE=
.


====Loading a constant field using a translation table====

At times, you might want to specify a field to add to a <var class="product">Model 204</var> record rather than taking a value from the input record. To do this, write a read-and-load-a-field statement that specifies a position and length of zero and a translation table that has one entry:
<var class="term">fieldname</var>=0,0,X'0400'
<var class="term">value</var>=
.


Position zero is a special case that makes no reference to the current input record. For example, if the personnel records for more than one company are kept in the <code>PEOPLE</code> file, the records for each company can be loaded in separate File Load runs.

For a particular run, the following example adds the field <code>COMPANY=Rocket</code> to every record loaded during that run:
COMPANY=0,0,X'0400'
Rocket=
.


===Load zero fields as '0' (X'0200')===

Mode bit X'0200' loads all-zero fields as '0'. This option is valid only if used in conjunction with mode bit X'0100' (strip leading zeroes). Use mode bits X'0100' and X'0200' together to strip leading zeroes, but to ensure that a field containing all zeros is stored as '0'. This is useful when a zero field and a missing field have different meanings in the database. 

===Strip leading zeros (X'0100')===

To compress values, you can strip all leading zeroes from certain field values before they are loaded into the <var class="product">Model 204</var> file using mode bit X'0100'. If a field contains all zeroes, it is stripped completely and is not stored. Unless blank deletion is suppressed, blanks are stripped before zeroes. 

===Read and load floating-point data (X'0080')===

Mode bit X'0080' indicates that the incoming data contains floating- point input. If the field to be loaded is not <var>FLOAT</var>, the field value is converted to a character string for storage. If the field is <var>FLOAT</var>, the value is stored with no conversion. 

With the mode bit turned off, character string input to a <var>FLOAT</var> field is converted to a floating-point value, if possible. Exponent format input is converted to numeric form for storage in <var>FLOAT</var> fields, and is left unconverted for non-<var>FLOAT</var> fields.

Floating-point format input to a <var>FLOAT</var> field is stored without conversion, but might be truncated or rounded, depending on its length. For more information about storing values in floating-point fields, see [[Floating point conversion, rounding, and precision rules]]. 

==File Load statements: loading a new Model 204 file==

The statements that can be used in a file load program are summarized here. Most file load statements are sensitive to the column in which they begin; note the specifications carefully. 
Note:
The file load statements use the vertical bar (<tt>|</tt>) character (that is, the character that has the hexadecimal value X'4F'). If the vertical bar is not available on the terminal being used for the File Load run, use the up-arrow (<tt>↑</tt>) or caret (<tt>^</tt>) instead. The broken vertical bar symbol available on some ASCII terminals is not equivalent to the vertical bar. Use the up-arrow or caret for these terminals.

===G (go to the next logical record) statement===

The <var>G</var> statement consists simply of the letter <code>G</code> in column 1. This statement causes the next logical record of the input data set to be positioned for processing. 

====Syntax====
G


Various other file load statements can then refer to the data in the input record by specifying a relative position within the record. If the input records are of fixed or undefined length (RECFM = F, FB, or U), the data starts in position 1. If the records are of variable length (RECFM = V or VB), the data starts in position 5, and the binary length of the data is in positions 1 and 2.

If no more input records remain, the file load program terminates and <var class="product">Model 204</var> goes on to the command that follows the <var>END</var> statement.

===* statement (comment line)===
Comment lines can be inserted anywhere in the file load program. Comment lines must have an asterisk in column 1.

====Syntax====
* This is a comment


===Read-and-load-a-field statement===

The read-and-load-a-field statement stores a field (in a <var class="product">Model 204</var> record) that contains the specified field name and a value extracted from the specified positions of the current input record. 

====Read-and-load-a-field statement processing====

Before the value is stored, leading and trailing blanks are deleted from it for the sake of space saving and uniformity. (In retrieval specifications, <var class="product">Model 204</var> considers <code>'MALE'</code> and <code>'MALE '</code> to be separate and distinct values.) Internal blanks are not changed in any way; for example: <code>'A B'</code> is stored as <code>'A B'</code> and not as <code>'AB'</code> or <code>'A B'</code>.

If the specified data area is entirely blank, then deleting the blanks reduces the length of the value to zero and the field is not stored. To load null values, use the <var>LOADNULLS ON</var> statement as described on [[#LOADNULLS statement|LOADNULLS statement]]. Deleting leading and trailing blanks can be suppressed by using mode bits after the length specification.

====Syntax====
fieldname=position,length,mode_bits

Where: 
<ul>
<li><var class="term">fieldname</var> must start in column 2 and must be defined before running the file load program. <var class="term">fieldname</var> must be followed immediately by the equal sign with no intervening blanks. </li>

<li><var class="term">position</var> denotes the starting position of the field's value within the input record currently being processed and is always a positive number. (Position zero has a special significance that is explained in [[#Loading a constant field using a translation table|Loading a constant field using a translation table]].)</li>

<li><var class="term">length</var> specifies the number of characters allotted to the value in the input record.</li>

<li><var class="term">mode_bits</var> are optional and are described beginning on [[#File Load statements: mode bits|File Load statements: mode bits]].</li>
</ul>

===Load-constant (LDC) statement===

The LDC statement loads a constant value into a field.
It is more efficient for loading a constant field than the translation table method described in [[#File Load statements: mode bits|File Load statements: mode bits]].

====Syntax====
LDC fieldname=value=mode_bits


Where: 
<ul>
<li><var>LDC</var> begins in column 1.</li>

<li><var class="term">fieldname</var> is the Model 204 field into which the constant value is to be loaded.</li>

<li><var class="term">mode_bits</var> are optional and are the same as those described beginning on [[#File Load statements: mode bits|File Load statements: mode bits]]. </li>

<li>Equal signs (<tt>=</tt>) are value delimiters. </li>
</ul>

====Examples====
The following examples use the LDC statement:
<ul>
<li>Load the value <code>1176 B</code> into field <code>DEPT NO</code>:
LDC DEPT NO=1176 B=
</li>

<li>Load the value <code>BOSTON</code> into the field <code>CITY</code> and begin a new <var class="product">Model 204</var> record:
LDC CITY=BOSTON=X'8000'
</li>
</ul>

===LOADNULLS statement===

The <var>LOADNULLS</var> statement allows you to determine how to treat null values. Null values (values with a string length of zero) occur when you delete a data area that is blank.

====Syntax====
LOADNULLS [ON | OFF]


Where:
<ul>
<li><var>ON</var> means that null values are loaded, the default.</li>
<li><var>OFF</var> means that null values are not loaded.</li>
</ul>

If <var>LOADNULLS</var> is not specified, the initial <var>FLOD</var> state is set to <var>LOADNULLS OFF</var>. 

===Load-repeating-field (LDRF) statement===

The <var>LDRF</var> statement loads a variable number of occurrences of a fixed length field of an input record into a multiply occurring field of a <var class="product">Model 204</var> record. If the number of occurrences of the fixed length field varies between input records, each input record must contain a field that specifies the number of occurrences. If the number of occurrences of the fixed length field is the same in all input records, the constant value can be loaded into a string buffer, and the <var>LDRF</var> statement can refer to the string buffer. The fixed length fields must be adjacent in the input record. 

====Syntax====
LDRF fieldname=pos1,len1,pos2,len2[,index][,mode_bits]



Where:
<ul>
<li><var>LDRF</var> must begin in column 1.</li>

<li><var class="term">pos1</var> is the starting position within the input record of the first occurrence of the fixed length field.</li>

<li><var class="term">len1</var> is the length of each occurrence of the field.</li>

<li><var class="term">pos2</var> is an EBCDIC number representing the number of occurrences of the fixed length field.</li>

<li><var class="term">len2</var>, in bytes, is the length of the number in <var class="term">pos2</var>.</li>

<li><var class="term">index</var> is optional and specifies an index register that points, after execution of the statement, to the record position just past the last occurrence loaded.</li>

<li><var class="term">mode_bits</var> are optional and described starting on [[#File Load statements: mode bits|File Load statements: mode bits]]. </li>

<li>The <var class="term">pos2</var> parameter is expected to be in EBCDIC. If this field is in the input record in some form, use the appropriate conversion statement (<var>CFB</var>, <var>CFF</var>, <var>CFP</var>, <var>CFZ</var>), with a string buffer. The string buffer can then be specified in the <var>LDRF</var> statement as the <var class="term">pos2</var> parameter. See [[#File Load statements: manipulating data areas with string buffers|File Load statements: manipulating data areas with string buffers]] for more information about converting values. </li>
</ul>

====Example====

For example, consider a file load program input file for a personnel database. The records might contain skill data that is likely to be multiply occurring. If the skill fields begin at position 45 of the input record, the length of each field is 15 bytes, a two-character EBCDIC occurrence count exists at record position 10, and the data is to be loaded into fields named <code>SKILL</code>, the following statement loads the fields:
LDRF SKILL=45,15,10,2


===Label definition (#) statement===

Labels can be defined within a file load program by a statement in the form:

#n


Where: 
<ul>
<li><var>#</var> (pound sign) is in column 1, and it is the label delimiter.</li>

<li><var class="term">n</var> is a positive number. The minimum value for <var class="term">n</var> is 1 (see [[#File load program execution|File load program execution]]). The maximum is either 4095 or the value of the parameter <var>[[LNTBL parameter|LNTBL]]</var>, whichever is smaller. </li>
</ul>

====Usage====

Labels are used by these other file load statements:
<ul>
<li>Unconditional branch</li>
<li>Branch-on-character-equal</li>
<li><var>CASE</var> statements that transfer execution from one part of the procedure to another.</li>
</ul>

These related statements are discussed in the following sections.

===Unconditional branches===

To force the execution of a file load program to transfer unconditionally to a statement other than the next one in line, specify a statement in the following form in column 1:
=label


Where: 

<var class="term">label</var> is the "<var class="term">n</var>" portion of the label as described in the previous section. 

===Branch-on-character-equal (=) statement===

The branch-on-character-equal statement allows the execution of a file load program to transfer to a different part of the procedure if the character at a specified position of the input record is equal to a specified character. 

====Syntax====
=label,position,character


Where:
<ul>
<li><var>=</var> (equal sign) is in column 1.</li>

<li><var class="term">label</var> is the "<var class="term">n</var>" portion of the label defined elsewhere in the procedure.</li>

<li><var class="term">position</var> denotes the position of the character in the input record to be compared.</li>

<li><var class="term">character</var> is the EBCDIC character to which the input character is compared. If the characters are equal, execution is transferred to the file load statements following the specified label. </li>
</ul>

====Usage====

This statement can compare only one character at a time. The EBCDIC character must immediately follow the second comma in the statement. Be careful about what EBCDIC character you choose; you can only specify an unprintable character if the editor has special input capabilities. 

====Example====

In the following example, certain personnel input records contain the employee's sex (<code>F</code> or <code>M</code>) in column 8, and the employee's spouse's name in columns 20 through 35: 
FLOD -1,-1,0
G *Get a record from TAPEI
SEX=8,1,X'8000' *Start new rec, load SEX field
=10,8,M *Branch to label 10 if SEX is M
NAME OF HUSBAND=20,16 *Load husband's name
=11 *Branch to 11,skip wife's name
#10 *Branch here when SEX is M
NAME OF WIFE=20,16 *Load wife's name
#11 *Fall through to END statement
END


===CASE statement===

The <var>CASE</var> statement provides a character string compare and branch facility that allows the execution of a file load program to transfer to one of a number of other parts of the procedure based upon the contents of a data field at a specified position of the input record. 

====Syntax====
CASE position,length
 string1=label1
string2=label2
string3=label3
.
.
.
ENDCASE


Where:
<ul>
<li><var>CASE</var> begins in column 1.</li>

<li><var class="term">position</var> denotes the starting position of the character string in the input record to be tested.</li>

<li><var class="term">length</var> denotes the length of the character string. </li>

<li><var class="term">stringN=labelN</var> specifications form a branch table to indicate where to transfer control when the argument string is matched. Branch table entries must begin in column 2. <var>CASE</var> is limited to 25 or fewer entries.</li>

<li><var>ENDCASE</var>, starting in column 1, must be used to terminate the branch table. </li>
</ul>

====Usage====

The <var>CASE</var> statement recognizes a match only if the content and length of the input record string argument are identical to the string value and length of one of the branch table entries. If no branch table entry matches the input record string argument, control passes to the statement following <var>ENDCASE</var>.

====Example====

Consider the following example:
CASE 37,4
JUNE=6
JULY=7
MAY =2
ENDCASE


When the <var>CASE</var> statement is executed, the four-character string that starts at position 37 of the input record is compared to each table entry. A match on content and length results in a branch to the procedure label following the <code>=<code>. Thus, if an input record contained <code>JUNE</code> in positions 37-40, control is transferred to procedure label 6. If the record contained <code>JULY</code> or <code>MAY</code>, control is passed to label 7 or 2, respectively.

The table entry for <code>MAY</code> in the previous example was expanded to four bytes. If the table entry is as follows, a match does not occur because its implies string length is 3:
MAY=2


The comparison is of data content and length. Applications of the <var>CASE</var> statement, in which the length of the strings in the branch table vary, can be handled by using a file load program index register for the <var>CASE</var> length specification. Index registers are discussed in [[#File Load statements: working with index registers|File Load statements: working with index registers]].

===Transfer-on-condition (T) statement===

Use the transfer-on-condition statement to compare two data areas of the input record and to transfer to a specified label if the comparison indicates a specified condition. 

====Syntax====
T label,position1,length,position2,condition


Where:
<ul>
<li><var>T</var> is in column 1. </li>

<li><var class="term">label</var> is the "<var class="term">n</var>" portion of the specified label (see previous statements about labels).</li>

<li><var class="term">position1</var> is the position of the first data area.</li>

<li><var class="term">length</var> specifies the number of characters.</li>

<li><var class="term">position2</var> is the position of the second data area. Each data area is taken to be and is treated as a simple EBCDIC character string.</li>

<li><var class="term">condition</var> is represented by a decimal number, as follows:
<table>
<tr class="head">
<th>Code</th>
<th>Meaning</th>
</tr>

<tr>
<td align="right"> 2</td>
<td>Greater than</td>
</tr>

<tr>
<td align="right"> 4</td>
<td>Less than</td>
</tr>

<tr>
<td align="right"> 7</td>
<td>Not equal to</td>
</tr>

<tr>
<td align="right"> 8</td>
<td>Equal to</td>
</tr>

<tr>
<td align="right"> 11</td>
<td>Greater than or equal to</td>
</tr>

<tr>
<td align="right"> 13</td>
<td>Less than or equal to</td>
</tr>
</table></li>
</ul>

====Example====

The following example transfers to label 40, if the character string in columns 3 through 12 is greater than that in columns 31 through 40:
T 40,3,10,31,2


===Read a field name from input data (D) statement===

In some circumstances, the input data contains the names of the fields to be loaded as well as the values. The <var>D</var> statement is similar to the read-and-load-a-field statement except that it also specifies the position and length of the field name within the current input. 

====Syntax====
D position1,length1=position2,length2[,mode_bits]


Where: 
<ul>
<li><var>D</var> is in column 1.</li>

<li><var class="term">position1</var> and <var class="term">length1</var> specify the position and length of the data area that contains the field name. Leading and trailing blanks are deleted.</li>

<li><var class="term">position2</var> and <var class="term">length2</var> specify the position and length of the data area that contains the field value.</li>

<li><var class="term">mode_bits</var> are optional and identical to the optional mode bits in [[#File Load statements: mode bits|File Load statements: mode bits]]. </li>
</ul>

====Example====

Suppose that input statements are arranged so that each statement contains a field name in columns 2 through 31 and a field value in columns 32 through 80. Furthermore, column 1 contains a 1 if the field is the first field of a new record and a 2 otherwise. The input records are:
1SOC.SEC.NO 540237398
2NAME THORNHILL
2DEPT ACCOUNTING
1SOC.SEC.NO 239876433
2NAME DARCY
.
.
.


The following file load program loads the records:
FLOD -1,-1,0
G *Read new input record
=10,1,2 *Branch to 10 if rec starts with 2
D 2,30=32,49,X'8000' *Load first fld of Model 204 rec
=20 *Branch to label 20
#10
D 2,30=32,49 *Add a field to Model 204 record
#20
END


===Print a character string (P) statement===

Use the <var>P</var> statement to print selected portions of the current input record or of a string buffer. 

====Syntax====
P position,length


Where:
<ul>
<li><var>P</var> is in column 1.</li>
<li><var class="term">position</var> indicates the starting position on the input record or string buffer.</li>
<li><var class="term">length</var> indicates the number of bytes of data to be printed from the input record or string buffer. </li>
</ul>

====Example====

The following statement can be used to print out sample input data:
FLOD -1,50,0
G
P 1,80
END


This statement prints 50 input records of 80 bytes each.

The <var>P</var> statement also is useful for printing out input records that are not in an expected format. The following procedure prints out input records that contain something other than an <code>X</code> or a <code>Y</code> in column 1:
FLOD -1,-1,0
G
=10,1,X * Branch to 10 if first column is X.
=20,1,Y * Branch to 20 if first column is Y.
P 1,80 * Print bad input record.
=30 * Don't process bad record.
#10
.
. * Process X records.
.
=30
#20
.
. * Process Y records.
.
#30
END


===STOP statement===

The <var>STOP</var> statement allows a file load program to exit before the number of records in the data set or specified in the file load program have been processed. 

====Syntax====
STOP return_code


Where <var class="term">return_code</var> is an optional, nonzero number. This number sets the job step return code for the file load program step. 

====Usage====

When the <var>STOP</var> statement is executed, the file load program ends evaluation of the statements in the procedure and displays the following message:
*** M204.0697: FLOD FINISHED -- STOP STATEMENT


When the file load program <var>STOP</var> statement executes, it ends the program, but not any of the other commands contained in the job stream.

==File Load statements: manipulating data areas with string buffers==

Two 256-byte areas, called string buffers, are provided to allow you to manipulate and reformat data areas before they are loaded. Use string buffers when: 
<ul>
<li>Input contains a long data area that is continued over two or more input records</li>
<li>Number of data areas are to be combined, reordered, or reformatted before loading</li>
<li>Using a numeric conversion statement (<var>CFB</var>, <var>CFP</var>, <var>CFF</var>, or <var>CFZ</var>)</li>
<li>Using an <var>L/ENDL</var> loop (see [[#L...ENDL statement (locate existing records)|L...ENDL statement (locate existing records)]]) </li>
</ul>

Use the following statements to manipulate the contents of the string buffers.
<table>
<tr class="head">
<th>Statement</th>
<th>Meaning</th>
</tr>

<tr>
<td>S </td>
<td>Clears the string buffer; moves a character string into the buffer</td>
</tr>

<tr>
<td>SC</td>
<td>Clears the string buffer; moves a constant into the buffer</td>
</tr>

<tr>
<td>M</td>
<td>Appends (moves) a character string into the buffer without clearing</td>
</tr>

<tr>
<td>MC</td>
<td>Appends (moves) a constant into the buffer without clearing</td>
</tr>

<tr>
<td>CFB</td>
<td>Converts from binary</td>
</tr>

<tr>
<td>CFF</td>
<td>Converts from floating-point</td>
</tr>

<tr>
<td>CFP</td>
<td>Converts from packed decimal</td>
</tr>

<tr>
<td>CFZ</td>
<td>Converts from zoned decimal</td>
</tr>
</table>

===Referring to string buffers===

Any statement that refers to the normal input record can also refer to a string buffer. A position field in any statement can be modified to refer to the string buffer instead of the input record using the following format:

=position, {|0S | |1S}


====Examples====

The following example branches to label 12 if column 37 of string buffer 0 contains an <code>A</code>:
=12,37|0S,A


The following example loads a field called <code>DATE</code> with a value taken from the first six columns of string buffer 1:
DATE=1|1S,6


The length of the current contents of a string buffer is remembered by <var class="product">Model 204</var> and can be used in any statement that contains a length field. This is done by immediately following the length with a vertical bar, the string buffer number, and the letter <code>S</code>. This causes the current length of the specified string buffer to be added to the length field.

Therefore, the length field normally is specified as zero.

The following example loads a field called <code>DATE</code> with a value equal to the current contents of string buffer 1:
DATE=1|1S,0|1S


The following example transfers to label 20, if the current contents of string buffer 0 are less than or equal to (condition 13) the contents of the date area beginning at column 73 of the current record:
T 20,1|0S,0|0S,73,13


For example, certain input records contain Social Security numbers in the form 123-45-6789 in columns 21 through 31. The following code removes the hyphens before the numbers are loaded into the <var class="product">Model 204</var> file:
S 0,21,3 * Blank buffer; load 3 digits.
M 0,25,2 * Add middle 2 digits.
M 0,28,4 * Add last 4 digits.
SOC.SEC.NO=1|0S,9 * Load number from buffer.


===S statement===

The <var>S</var> statement clears the contents of the specified string buffer to blanks and then moves in a character string from the current input record. The string is left-justified in the string buffer. 

====Syntax====

The format of the <var>S</var> statement is: 

S {0 | 1},position,length


Where: 
<ul>
<li><var>S</var> begins in column 1.</li>
<li>0 and 1 are string buffers.</li>
<li><var class="term">position</var> is the starting column number from which to read characters from the current input record.</li>
<li><var class="term">length</var> is the number of characters to read.</li>
</ul>

====Examples====

The following example clears buffer 0 and moves 11 characters from columns 29 through 39 of the current input record into the beginning of the buffer:
S 0,29,11


The following example clears string buffer 1 and inserts the character from column 3 of the input:
S 1,3,1


The following example simply clears string buffer 0:
S 0,1,0


===M statement===

The <var>M</var> statement is almost identical to the <var>S</var> statement except that the string buffer is not cleared first. Characters from the input record are simply appended to the existing contents of the buffer. 

====Syntax====

The format of the <var>M</var> statement is: 

M {0 | 1},position,length


===SC statement===

The <var>SC</var> statement clears the contents of the specified string buffer to blanks and then moves in a constant. 

====Syntax====

The format of the <var>SC</var> statement is: 
SC {0 | 1},value=


Where: 
<ul>
<li><var>SC</var> begins in column 1.</li>
<li>0 and 1 are string buffers.</li>
<li><var class="term">value</var><var>=</var> is any constant string. You <var class="term">must</var> specify the final equal sign. The constant can be up to 256 characters long.</li>
</ul>

====Example====

The following example clears buffer 0 and moves the constant value, 7, into the beginning of the buffer:
SC 0,7=


===MC statement===

The <var>MC</var> statement is almost identical to the <var>SC</var> statement except that the string buffer is not cleared first. A constant value is simply appended to the existing contents of the buffer. 

====Syntax====

The format of the <var>MC</var> statement is:

MC {0 | 1},value=


===Data conversion statements===

You can use string buffers as an intermediate storage area while converting input data from binary, packed decimal, zoned decimal, or floating-point to EBCDIC for storage in the <var class="product">Model 204</var> file. Numeric data must be translated to character form if the data is to be accessible to a SOUL user.

These statements are described in detail in the following sections.

===CFB (convert from binary) statement===

To allow you to translate from binary input data to a character string format for use in <var class="product">Model 204</var>, the convert-from-binary instruction is provided. 

====Syntax====

The statement format is:

CFB {0 | 1},position,length


Where:
<ul>
<li><var>CFB</var> starts in column 1.</li>
<li>0 and 1 are string buffers.</li>
<li><var class="term">position</var> indicates where the binary data in the input record begins.</li>
<li><var class="term">length</var> can be from 1-4 bytes. </li>
</ul>

====Usage====

The data in the specified position must be a 1- to 4-byte signed binary number. The <var>CFB</var> instruction converts it to EBCDIC and stores it in the designated string buffer where it can be edited and/or loaded into the <var class="product">Model 204</var> file. Leading integer zeroes are stripped during conversion. 

The first character of the result is either a significant digit or a minus sign (<tt>-</tt>). If the input value is a zero, the result is a single zero. 

====Example====

For example, the following sequence converts a 2-byte binary field beginning in Position 4 of the input record to EBCDIC, leaving the result in string buffer 1:
CFB 1,4,2
QUANTITY=1|1S,0|1S


The EBCDIC string is loaded from string buffer 1 into the <code>QUANTITY</code> field of the current record.

===CFF (convert from floating-point) statement===

The convert-from-floating-point instruction converts short- or long-floating-point input data to a character string format for use in <var class="product">Model 204</var>.

====Syntax====

The statement format is:

CFF {0 | 1},position,length


Where: 
<ul>
<li><var>CFF</var> starts in column 1.</li>
<li>0 and 1 are string buffers.</li>
<li><var class="term">position</var> indicates where the binary data in the input record begins.</li>
<li><var class="term">length</var> depends on the form of the input data. The input data can be either a short- or long-precision floating-point number. Length must be:
<ul>
<li>4 for a short-precision number</li>
<li>8 for a long-precision number</li>
</ul>
Note:
If <var class="term">length</var> is specified incorrectly (neither 4 nor 8), a zero length results and no error indication is given. </li>
</ul>

====Usage====

Leading integer zeros and trailing fractional zeros are stripped during conversion. A decimal point is not included for an integer value. If the input value is a zero, the result is a single zero. If the input value is a negative number, the first character of the result is a minus sign. The result of the conversion has at least 15 digits of precision. The result of a CFF instruction can be loaded into a <var class="product">Model 204</var> record using a read-and-load-a-field statement, as shown in the following example.

====Example====
CFF 1,20,8
AMOUNT=1|1S,0|1S


For information about loading floating-point input directly into a field, see [[#Read and load floating-point data (X'0080')|Read and load floating-point data (X'0080')]].

===CFP (convert from packed decimal) statement===

To allow you to translate from packed decimal input data to a character string format for use in <var class="product">Model 204</var>, the convert-from-packed instruction is provided. 

====Syntax====

The statement format is:

CFP {0 | 1},position,length[,decimal_position]


Where: 
<ul>
<li><var>CFP</var> starts in column 1.</li>

<li>0 and 1 are string buffers.</li>

<li><var class="term">position</var> indicates where the packed data in the input record begins.</li>

<li><var class="term">length</var>, specified in bytes rather than packed decimal digits, must be between 1 and 8.
Note:
If the length is specified incorrectly (less than 1 or greater than 8) a zero length results and no error indication is given.</li>

<li><var class="term">decimal_position</var> indicates where a decimal point can be inserted into the string, expressed as a number of digits to the right of the desired decimal point. </li>
</ul>

====Usage====

The data in the specified position must be a 1- to 8-byte packed decimal number, which starts on a byte boundary and, therefore, consists of an odd number of digits. This data is not checked for conformity to a packed decimal format. A number is assumed to be positive unless its sign position contains a valid minus sign.

The <var>CFP</var> instruction converts the data to EBCDIC and stores the result in the designated string buffer, where it can be edited and/or loaded into the <var class="product">Model 204</var> file. The first character of the result is either a blank or a minus sign, and leading and trailing zeros are not stripped. If a decimal position is specified, a decimal point is inserted in the string. If the decimal position is invalid (less than zero or greater than the number of digits in the input), a message is issued and the decimal point is not inserted. 

====Example====

The following sequence converts a 6-byte packed decimal field beginning in Position 8 of the input record to EBCDIC, leaving the result in string buffer 1 with a decimal point inserted, giving the number two decimal places:
CFP 1,8,6,2
AMOUNT=1|1S,0|1S


The result has the form:
sddddddddd.dd


Where: 
<ul>
<li><var class="term">s</var> represents a blank or minus sign. </li>
<li><var class="term">d</var> represents a digit between 0 and 9. </li>
</ul>

This result is then loaded into the <code>AMOUNT</code> field of the current record from string buffer 1.

===CFZ (convert from zoned decimal) statement===

To allow translation from zoned decimal input data to a character string format for use in <var class="product">Model 204</var>, the convert-from-zoned instruction is provided. 

====Syntax====

The statement format is:

CFZ {0 | 1},position,length[,decimal_position]


Where: 
<ul>
<li><var>CFZ</var> starts in column 1.</li>
<li>0 and 1 are string buffers.</li>
<li><var class="term">position</var> indicates where the zoned data in the input record begins.</li>
<li><var class="term">length</var>, specified in bytes, must be between 1 and 16. If the length is specified incorrectly (less than 1 or greater than 16), a zero length results and no error indication is given.</li>
<li><var class="term">decimal_position</var> indicates where a decimal point can be inserted into the string, expressed as the number of digits to the right of the desired decimal point. </li>
</ul>

====Usage====

The data in the specified position must be a 1- to 16-byte zoned decimal number. The data is not checked for conformity to a zoned decimal format. If the zone of the low-order byte is not a valid minus sign, the number is assumed to be positive.

The <var>CFZ</var> instruction converts the data to EBCDIC and stores the result in the designated string buffer where it can be edited and/or loaded into the <var class="product">Model 204</var> file. The first character of the result is either a blank or a minus sign, and leading and trailing zeroes are not stripped. If the decimal position is invalid (less than 0 or greater than the number of digits in the input), a message is issued and the decimal point is not inserted. 

====Example====

The following sequence converts a 6-byte zoned decimal field beginning in position 20 of the input record to EBCDIC, leaving the result in string buffer 1 with a decimal point inserted, giving the number two decimal places:
CFZ 1,20,6,2
PAYMENT=1|1S,0|1S


The result has the form:
sdddd.dd


Where:
<ul>
<li><var class="term">s</var> represents a blank or minus sign.</li>
<li><var class="term">d</var> represents a digit between 0 and 9. </li>
</ul>

This result is then loaded into the <code>PAYMENT</code> field of the current record from string buffer 1. 

==File Load statements: working with index registers==

A number of work areas called index registers, which are used primarily to manipulate numbers, are available for use within file load programs. The numbers in these index registers are most often used to modify the position or length fields of other file load statements.

====Number of allowable registers====

Index registers are denoted by index register numbers that can range from 1 to the value of the parameter <var>LNTBL</var>, which defaults to 50 (see [[#File load program execution|File load program execution]]). The maximum number of index registers is 255, no matter how large <var>LNTBL</var> is. 

====Index register size====

Each index register is four bytes long (a fullword) and can contain number values between -2,147,483,648 and +2,147,483,647, inclusive. 

===Setting an index register===

The <var>I</var> statement has a fairly complicated format. A number of simple forms are discussed first. 

====Syntax====

The basic statement format is:

I index,[operands]


Where:
<ul>
<li><var>I</var> is in column 1. </li>
<li><var class="term">index</var> is the number of the index register to be set.</li>
<li><var class="term">operands</var> are optional operations that modify the indicated index register and can involve input records or other index registers. </li>
</ul>

===Clearing an index register===

If no optional operands are specified, the <var>I</var> statement sets the specified index register to zero. The following example sets index register 15 to zero:
I 15


===Setting an index register from the input record===

As many as four bytes of data from the current input record can be loaded into an index register, using the following format:

I index,position,length


Where <var class="term">length</var> is the number of bytes of data starting at the specified position that are placed into the specified index register right-aligned and padded with binary zeros on the left if length is less than 4. 

====Example====

The following example loads the first two bytes of the input record into index register 9:
I 9,1,2 

If the input records are variable-length (RECFM=V or VB), index register 9 contains the number of characters of data in the record.


===Setting an index register to a constant===

To set an index register to a specified number:

====Syntax====
I <var class="term">index</var>,,,<var class="term">number</var>


Where <var class="term">number</var>, which can be specified in decimal, hexadecimal (X'xx'), or character (C'c') form, must be between -32,768 and +32,767, inclusive (two bytes). If a larger value is specified, only the low-order two bytes are used.

====Example====

The following example sets index register 35 to minus one:
I 35,,,-1


===Adding to an index register===

A number can be added to the contents of an index register and stored back into that register or some other register.

====Syntax====
Use the following format:
I index1,,,number|index2


The number must conform to the previous rule for a constant.

====Examples====

For example, suppose that index register 23 contains the number 119. The following example sets index register 7 to 124. Register 23 still contains 119:
I 7,,,5|23


The following example changes the contents of register 23 from 119 to 99:
I 23,,,-20|23


===Multiplying the contents of an index register===

The contents of an index register can be multiplied by a specified number and the result stored into that register or some other register.

====Syntax====
Use the following format:
I index1,,,,number|index2


The number must conform to the rule given above for a constant.

====Examples====

For example, suppose that index register 4 contains the number 10. The following example sets index register 5 to -10. Register 4 still contains 10:
I 5,,,,-1|4


The following example changes the contents of register 4 from 10 to 70:
I 4,,,,7|4


===Full format of I statement===

The full format of the <var>I</var> statement is:

I index1,position,length,number2|index2,number3|index3


In this full format the I statement computes the sum of these four quantities: 
<ul>
<li>Data field of <var class="term">length</var> bytes at the specified position of the current input record</li>
<li><var class="term">number2</var></li>
<li>Contents of <var class="term">index2</var></li>
<li>Product of <var class="term">number3</var> and the contents of <var class="term">index3</var> </li>
</ul>

The sum is then stored in <var class="term">index1</var>.

<var class="term">length</var> cannot exceed 4. 

<var class="term">number2</var> and <var class="term">number3</var> should follow the rule given above for a constant.

====Example====

The following example adds the two bytes at the beginning of the input record, the contents of index register 15, and the contents of register 16, and stores the result in register 14:
I 14,1,2,0|15,1|16


===Modifying position and length fields===

The position or length fields of most file load statements can be modified by the contents of any index register by immediately following the field with a vertical bar and the number of the index register. That is:

index


The contents of the index register are added to the position or length number preceding the vertical bar. 

====Examples====

For example, if index register 18 contains 5, the following example branches to label 40 if column 8 of the current input record contains a semicolon (<tt>;</tt>): 
=40,3|18,;


Suppose that an input record contains a data area in columns 20 through 39 that has a person's name in the format:
<var class="term">last_name,first_name</var>


The following code loads a <code>LAST NAME</code> field composed of everything up to the comma:
I 4 *Clear index register 4
#31 *Top of comma loop check
=32,20|4,, *Branch to label 32 if comma found
I 4,,,1|4 *Add one to register 4
=31 *Branch back to label 31
#32
LAST NAME=20,0|4 *Load last name (length in reg 4)


===Referring to the contents of index registers===

In some cases, an index register can be treated as a data area itself. As such, the index register can be viewed as being four characters long (containing positions 1 through 4).

Any file load statement that has a position field can refer to a position in a specified index register by replacing:

<var class="term">position</var>


with:
<var class="term">indexposition</var>|<var class="term">index</var>*


Where:
<ul>
<li><var class="term">indexposition</var> is 1, 2, 3, or 4 (position 1 is the high-order position).</li>
<li><var class="term">index</var> specifies the desired index register. The asterisk replaces the comma that normally follows the position specification. </li>
</ul>

The following example branches to label 40 if position 4 of index register 11 contains the EBCDIC character 3:
=40,4|11*3


The EBCDIC representation for 3 is equal to the number <code>X'F3'</code>, or decimal 243. 

====Example====

The following example branches to label 35 if the contents of positions 1 through 4 of index register 11 are equal to (condition 8) positions 1 through 4 of register 12. In other words, the following instruction simply compares two index registers: 
T 35,1|11*4,1|12*8


===Printing an index register value===

The <var>Q</var> statement prints the current numeric value of a specified index register as a decimal number. 

The format is:
Q index


===File Load statements: updating existing Model 204 records===

You can use file load programs to update or retrieve data from existing records in the <var class="product">Model 204</var> file as well as to load new records. The <var>FLOD</var> command and JCL are identical to those used for loading new records. The following special purpose file load statements can be used within file load programs to locate existing records, add fields, or determine the current value of an existing field.

===L...ENDL statement (locate existing records)===

The <var>L</var> statement provides a means of locating all the existing records in the <var class="product">Model 204</var> file with a specified field name = value pair. The field must be a <var>KEY</var> or <var>ORDERED</var> field. One pass is then made through a locate loop of file load statements for each record located in this way.

Beginning in <var class="product">Model 204</var> V4R2.0, the <var>L</var> statement supports the <var>ORDERED</var> attribute as well as the <var>KEY</var> attribute. Prior to V4R2.0, you might have defined fields in your files with both the <var>KEY</var> and <var>ORDERED</var> attributes, because you needed the <var>KEY</var> attribute for File Load <var>L</var> statement usage. In such cases, removing the <var>KEY</var> attribute eliminates Table C usage for that field and saves CPU time and disk I/O. 

During a particular pass, the located record becomes the current record (that is, the record updated by read-and-load-a-field statements, delete statements, and so on). If a new <var class="product">Model 204</var> record has begun before the L statement, it is remembered and becomes the current record again when all the located records have been processed by the locate loop. If no records contain the specified field name = value pair, no passes are made through the locate loop. 

A locate loop that follows an L statement consists of a sequence of file load statements followed by an <var>ENDL</var> statement. You can use any file load statement except one that transfers control to a label outside the loop (that is, a label that is not between the <var>L</var> and <var>ENDL</var> statements). 

====Syntax====
The format of the <var>L</var> statement is:

L {0 | 1},fieldname=index,label[,mode_bits]
.
.
.
ENDL


Where:
<ul>
<li><var>L</var> is in column 1.</li>

<li>0 or 1 specifies the number of a string buffer that contains the value portion of the field name = value pair.</li>

<li><var class="term">fieldname</var> must specify a field that has the <var>KEY</var> or <var>ORDERED</var> attribute.</li>

<li><var class="term">index</var> specifies the number of any unused index register. The index register is used as a work area by the locate loop.</li>

<li><var class="term">label</var> specifies a label to which control is to be transferred after passes have been made through the locate loop for all the located records. If no records are found by the <var>L</var> statement, control passes immediately to the label. For this reason, the statement after the <var>ENDL</var> always needs a label or it is not executed. </li>

<li><var class="term">mode_bits</var> are optional and described in [[#File Load statements: mode bits|File Load statements: mode bits]]. If default editing produces the wrong value, you must specify mode bits.</li>

<li><var>ENDL</var> ends the locate loop and must start in column 1.</li>
</ul>

====Usage====

Locate loops can be nested up to three levels. Each time an L statement is encountered, the current record is remembered and record processing is said to go down one level. When the lower locate loop has processed its records, the record processing goes up one level and the remembered record once again becomes the current record. Each nested locate loop operates a <var>FIND</var> against the whole file of records, not just on the found set of the previous loop. 

Nesting is shown in the following figure:

Locate Loop Nesting
[[File:Locate loop nesting.gif|346px]]

====Example====

Suppose that a <var class="product">Model 204</var> file contains personnel information that includes a last name field. The input data contains last names in columns 1 through 20 followed by as many as three homonyms in columns 21-40, 41-60, and 61-80:
FLOD -1,-1,0
G * Get new input record
S 0,1,20 * Move last name into buffer 0
L 0,LAST NAME=30,45 * FR WHERE LAST NAME = last name
HOMONYM=21,20 * Add Homonym Value
HOMONYM=41,20 * Add Homonym Value
HOMONYM=61,20 * Add Homonym Value
ENDL * END FOR
#45
END


For each input record, the previous procedure locates records that contain a <code>LAST NAME</code> equal to the value in columns 1 through 20. For each such record, as many as three <code>HOMONYM</code> fields are added.

A locate loop is quite similar to the following SOUL construction:
LOOP: FOR EACH RECORD WHERE fieldname = value
.
.
.
END FOR


===UP and DOWN statements (change record processing level)===

The current record processing position can be changed through use of the <var>UP</var> and <var>DOWN</var> statements. The <var>UP</var> and <var>DOWN</var> statements consist of words starting in column 1. They can be used only within locate loops: 
<ul>
<li><var>UP</var> statement causes record processing to go up one level. That is, the record that was remembered by the <var>L</var> statement once again becomes the current record and can be updated.</li>

<li><var>DOWN</var> statement reverses the process, and the record that the locate loop was processing at the time of the <var>UP</var> statement becomes the current record. </li>
</ul>

<var>UP</var> and <var>DOWN</var> statements must always occur in pairs.

An <var>L</var> statement performs the <var>DOWN</var> function automatically; an <var>ENDL</var> statement performs an automatic <var>UP</var>. 

====Example====

Suppose that a file contains two types of records: "people" records and "child" records. A number of child records are being loaded into the file. Each contains the name of the child's parent. It is assumed that the parent's record already is in the file. Moreover, the input data for the child records does not include addresses. As each child's record is loaded, this file load program locates the child's parent's record, reads its <code>ADDRESS</code> field, and copies it into the new child record:
FLOD -1,-1,0
G
.
.
.
PARENT.NAME=65,15 *Add PARENT.NAME to child's record
S 1,65,15 *Move parent's name into buffer 1
L 1,NAME=43,20 *FR WHERE NAME = parent's name
F 19,ADDRESS=30,33 * FEO address
UP * Make child's record current
ADDRESS=1|30,0|33 * Add address to child's record
DOWN * Make parent's record current
ENDF * END FOR
#19 * Transfer here at end of F loop.
ENDL *END FOR
#20 *Transfer here at end of L loop.
END


===F statement (read field values)===

The <var>F</var> statement provides a means of reading the current value(s) of a specified field within the current record. One pass is made through an <var>F</var> loop of file load statements for each occurrence of the field within the record. 

====Syntax====

The format of the <var>F</var> statement is:

F label,fieldname=index1,index2


Where:
<ul>
<li><var>F</var> is in column 1.</li>

<li><var class="term">label</var> specifies a label to which control is to be transferred after passes have been made through the <var>F</var> loop for all occurrences of the field.</li>

<li><var class="term">fieldname</var> must specify a field that has the <var>VISIBLE</var> attribute.</li>

<li><var class="term">index1</var> and <var class="term">index2</var> specify numbers of index registers not currently in use.

At the beginning of each pass through the <var>F</var> loop, the value of the field occurrence to be processed in that pass is placed in a special work area, and <var class="term">index1</var> is pointed at that work area. <var class="term">index2</var> contains the length of the current value. Thus, the statements within the <var>F</var> loop can refer to the current value by specifying a position of <code>1|<var class="term">index1</var></code> and a length of <code>0|<var class="term">index2</var></code>. 

After the last pass through the <var>F</var> loop, <var class="term">index1</var> and <var class="term">index2</var> still can be used to refer to the last value processed until another <var>F</var> statement is encountered. 

An <var>F</var> loop following an <var>F</var> statement consists simply of a sequence of file load statements followed by an <var>ENDF</var> statement. Any file load statement can be used except:
<ul>
<li>One that transfers control to a label outside the <var>F</var> loop</li>
<li><var>L</var> statement </li>
<li>Another <var>F</var> statement</li>
<li><var>DELETE</var> statement </li>
<li>Delete-field statement that deletes a <var>VISIBLE</var> field </li>
</ul></li>
</ul>

====Example====

The following statements delete the last occurrence of the <code>CHILD</code> field in the current record:
F 27,CHILD=35,36
ENDF
#27
CHILD=1|35,0|36,X'4000'


==File Load statements: deleting records and fields==

===Deleting a record===

The <var>DELETE</var> statement deletes the current <var class="product">Model 204</var> record from the file. This statement consists of the word <var>DELETE</var> in column 1. 

The following procedure deletes <var class="product">Model 204</var> records whose Social Security numbers correspond to those read from the input file:
FLOD -1,-1,0
G * Get an input record
S 1,1,9 * Move SSN to string buffer 1
L 1,SOC.SEC.NO=47,15 * FOR EACH matching M204 record
DELETE * Delete the record
ENDL * END FOR
#15
END


The <var>FLOD</var> run must be a multiuser run in order for the <var>NON-DEFFERABLE</var> attribute to take effect at all. How to set up a multiuser run so that the <var>NON-DEFERRABLE</var> attribute takes effect is described in [[Deferred update feature#Overriding deferred updates|Overriding deferred updates]]. 

Two variations of the read-and-load-a-field statement allow you to delete fields from the current record. One form is limited to deleting <var>VISIBLE</var> fields only. The other form can be used to delete <var>VISIBLE</var>, <var>INVISIBLE</var>, and multiply occurring fields. Descriptions of both variations follow.

===Deleting a VISIBLE field===

The format of the statement used to delete a <var>VISIBLE</var> field is:

fieldname=1,1,X'5800'


Where:
<ul>
<li><var class="term">fieldname</var> must start in column 2 and must specify a field that has the <var>VISIBLE</var> attribute. If the field occurs in the current record more than once (for example, a <code>CHILD</code> field), only the first occurrence is deleted.</li>

<li>1's are position and length indicators (as in the following subsection).</li>

<li>X'5800' is a combination of mode bit options (see [[#File Load statements: mode bits|File Load statements: mode bits]]). </li>
</ul>

====Example====

The following procedure changes the <code>ADDRESS</code> fields of <var class="product">Model 204</var> records whose Social Security numbers are provided in columns 1 through 9 of the input records. The new addresses are in columns 10 through 59:

FLOD -1,-1,0
G
S 0,1,9 * Move SSN into string buffer 0
L 0,SOC.SEC.NO=15,20 * FR WHERE SOC.SEC.NO=value
ADDRESS=1,1,X'5800' * Delete old address
ADDRESS=10,50 * Add new address
ENDL * END FOR
#20
END


===Deleting specific values===

Use this form of the read-and-load-a-field statement to delete any field value, even if it is <var>INVISIBLE</var> or a value in a multiply occurring field.

====Syntax====

The format of the statement used to delete a specific occurrence of a field is:

fieldname=position,length,X'4000'


Where:
<ul>
<li><var class="term">fieldname</var> must start in column 2 and is followed immediately by an equal sign.</li>

<li><var class="term">position</var> specifies the starting position within the current input record (or string buffer) of the specific value to be deleted.</li>

<li><var class="term">length</var> specifies the length of the value.</li>

<li>X'4000' is the mode bit option for deleting a field (see [[#File Load statements: mode bits|File Load statements: mode bits]]). </li>
</ul>

This delete-field statement differs from the first delete-field statement in the following ways:
<ul>
<li>Value must be specified as well as the field name.</li>
<li>Form can be used to delete <var>INVISIBLE</var> fields as well as <var>VISIBLE</var> fields.</li>
<li>It can be used to delete the second, third, and subsequent occurrences of a multiply occurring field, as well as the first occurrence. </li>
</ul>

===Deleting records===

The date-time stamp feature does not include support for <var>DELETE RECORD</var> or <var>DELETE RECORDS</var> processing. <var>DELETE RECORD</var> or <var>DELETE RECORDS</var> processing must be handled by your application software.

As well, you can use logical delete techniques. However, in all forms of deleting records, it is your responsibility to maintain a log of record deletions, if you want one.

====Handling the date-time stamp field in a file====

The <var>DELETE FIELD</var> command is prohibited for the <var>DTSFN</var> field in a file when the <var>FOPT</var> X'10' bit is set. Attempting to do so results in the following message:
M204.2727: CAN'T DELETE DTS FIELD WHEN FOPT=X'10' IS ON


==File load program execution==

===File load program phases===

The file load program is processed in two phases. First, all of the statements between the <var>FLOD</var> command and the <var>END</var> statement are compiled. If any errors are detected, such as invalid field names or field-level security violations, the file load program is not executed.

If the compilation is successful, the procedure is executed.

===Internal file load optimization feature===

Most file load programs add records to a new or partially loaded entry order file (where new records are always added at the end of the file). The internal file load optimization feature greatly optimizes file load program performance in such situations. 

The internal file load optimization feature also enhances performance when loading records into new or reinitialized Reuse Record Number (<var>RRN</var>) files. 

In other environments, such as sorted, hash key, and unordered files, or for file load programs containing statements that examine or modify data already in the file (<var>DELETE</var>, <var>F</var>, <var>L</var>, or a statement having the X'4000' (delete) mode bit), the internal file load optimization feature is automatically turned off. 

===Storage tables===

File load programs are compiled into various storage and work areas. These areas consist of the following tables: 
<table>
<tr class="head">
<th>This table</th>
<th>Contains...</th>
</tr>

<tr>
<td>NTBL</td>
<td>Label definitions and index registers. Each NTBL entry is shared by the label and index register having the same number. The size of NTBL determines the highest number that can be used. </td>
</tr>

<tr>
<td>QTBL </td>
<td>Statements in internal form. Each file load statement generates one QTBL entry. Entry sizes vary, but most entries are between 12 and 20 bytes long. Important exceptions are the read-and-load-a-field entry, which expands by 4 bytes for each entry in a translation table, and the <var>CASE</var> entry, which starts at 12 bytes and adds 8 bytes for every branch table entry. </td>
</tr>

<tr>
<td>STBL </td>
<td>All character strings specified for translation tables, <var>CASE</var> statements, and <var>LDC</var> statements. Each string is preceded by a 1-byte length. </td>
</tr>

<tr>
<td>VTBL </td>
<td>Compiler variables. A minimal amount of VTBL space is used if the file load program contains an L statement (locate loop). Entries are variable in length, but most range from 8 to 20 bytes. </td>
</tr>
</table>

The size of each table is determined by a parameter that can be set in the File Load job. These parameters are <var>LNTBL</var>, <var>LQTBL</var>, <var>LSTBL</var>, and <var>LVTBL</var>. For more information about these tables, see [[Large request considerations#Description of tables|Description of tables]]. 

===FLOD and FILELOAD exits===

<var>FLOD</var> or <var>FILELOAD</var> exits pass control from <var>FLOD</var> to an Assembler or COBOL program, which allows you more sophisticated data manipulation capabilities. For complete information about these exits, see [[FLOD exits]].

==Error conditions==

This section describes the file load program error conditions that <var class="product">Model 204</var> can encounter because of preallocated field and field-level security violations. 

Errors generated during file load program evaluation are counting errors, which are described in the <var class="book">[[Media:M204_TerminalUserGuide_V75.pdf|Rocket Model 204 Terminal User's Guide]]</var>. If the number of errors encountered during evaluation reaches the limit specified in the <var>ERMX</var> parameter, the file load program is terminated and the user is restarted. 

====File load performance====

The order in which fields are loaded affects the speed with which the file load program executes. This is particularly true when the go-faster feature is in effect. Execution speed can be optimized by loading preallocated fields before all other fields.

===Preallocated field violations===

If you try to load values in a preallocated field that are longer than the length specified in the field's <var>LENGTH</var> option or you try to add more occurrences to a preallocated field than are specified in the field's <var>OCCURS</var> option, an error is generated during the file load program evaluation. The value lengths specified in file load statements are not checked during compilation. Instead, actual value lengths are checked during evaluation, after blanks have been deleted and leading zeroes have been stripped. 

<var class="product">Model 204</var> handles length and occurrence errors by issuing time error messages that specify the relevant field name and the internal record number of the record that <var class="product">Model 204</var> was processing when the error was encountered.

Except in the case of the LDRF (load-repeating-field) statement, nothing is stored for the statement that causes the error, and evaluation continues with the next file load statement. For LDRF, the occurrence causing the error is not stored, but <var class="product">Model 204</var> attempts to load subsequent values.

===Field-level security violations===

All field-level security (FLS) violations, except those occurring in a <var>D</var> statement used to load field = value pairs from the input data, can be detected during compilation of a file load program. FLS violations detected during compilation result in counting error messages that prevent evaluation of the file load program. An FLS violation that results from the compilation of a <var>D</var> statement produces error messages that identify the input record number, the relevant field name, and the internal record number of the record that was being built when the error was encountered. The field is not stored in the file. 

===AT-MOST-ONE field violations===

When you use <var>FLOD</var> or <var>FILELOAD</var> to load or modify records that have <var>AT-MOST-ONE</var> fields, <var class="product">Model 204</var> ensures that the new or modified records do not violate <var>AT-MOST-ONE</var> constraints. <var class="product">Model 204</var> detects and reports all violations of <var>AT-MOST-ONE</var> in one pass of the input data. If <var class="product">Model 204</var> finds any fields that violate the constraints, the following occurs:
<ol>
<li>Error is reported and the new or duplicate field is rejected.</li>
<li><var>FLOD</var> continues processing the input data.</li>
<li>At the end of the run, the file is marked "logically inconsistent."</li>
<li>Following error message is issued for each violation:
M204.2119: AT-MOST-ONE CONSTRAINT VIOLATION IN RECORD <var class="term">recordnumber</var>, FIELD IGNORED: <var class="term">fieldname</var>=<var class="term">value</var>
</li>
</ol>

===NUMERIC VALIDATION file violations===

When loading or modifying records in <var>NUMERIC VALIDATION</var> files using <var>FLOD</var> or <var>FILELOAD</var>, <var class="product">Model 204</var> ensures that the new or modified <var>FLOAT</var> and <var>BINARY</var> fields do not violate <var>NUMERIC VALIDATION</var> constraints. <var class="product">Model 204</var> detects and reports all <var>FLOAT</var> and <var>BINARY</var> violations. If <var class="product">Model 204</var> finds any numeric data type violations, the following occurs:
<ol>
<li>Error is reported with one of the following messages and the field is rejected.</li>

<li><var>FLOD</var> (or <var>FILELOAD</var>) continues processing the input data.</li>

<li>At the end of the run, the file is marked "logically inconsistent;" that is, the <var>[[FISTAT parameter|FISTAT]]</var> parameter is set to X'40'.</li>

<li>One of the following error messages is issued for each violation:
M204.2123: VALUE SPECIFIED VIOLATES BINARY DATA TYPE VALIDATION IN RECORD <var class="term">recno</var>, FIELD IGNORED:
<var class="term">fieldname</var> = <var class="term">value</var>

M204.2124: VALUE SPECIFIED VIOLATES FLOAT DATA TYPE VALIDATION IN RECORD <var class="term">recno</var>, FIELD IGNORED:
<var class="term">fieldname</var> = <var class="term">value</var>
</li>
</ol>

==Syntax of File Load statements==

This section provides the complete syntax of the <var>FILELOAD</var> and <var>FLOD</var> commands and all the file load statements. 

===FILELOAD command===

The <var>FILELOAD</var> command has the following format:

====Syntax====
FILELOAD k,n,m [,[s1] [,[s2] [,[s3] [,[s4] [,vl]]]]]


Where:
<ul>
<li><var class="term">k</var> is the maximum number of records loaded.</li>

<li><var class="term">n</var> is the maximum number of passes through the file load procedure.</li>

<li><var class="term">m</var> is the number of input records to skip before starting the load process.</li>

<li><var class="term">s1</var> is the amount of memory used for sorting the deferred update index records.</li>

<li><var class="term">s2</var> is the amount of memory used for sorting the deferred update <var>FRV</var> index records.</li>

<li><var class="term">s3</var> is the amount of memory allocated for the two buffers used to pass data from <var class="product">Model 204</var> to the sorts.</li>

<li><var class="term">s4</var> is the amount of memory allocated for the two buffers used to pass data from the sorts to <var class="product">Model 204</var>.</li>

<li><var class="term">vl</var> is the maximum sort record length in variable-length record sorts. (<var class="term">vl</var> corresponds to the <var class="term">L2</var> of the <var>RECORD</var> sort statement.)

The <var class="term">vl</var> parameter must be present for one-step File Load runs that update <var>ORDERED</var> fields. </li>
</ul>

===FLOD command===

====Syntax====
FLOD k,n,m 


Where: 
<ul>
<li><var class="term">k</var>, <var class="term">n</var>, and <var class="term">m</var> have the same meanings as in <var>FILELOAD</var>. </li>
</ul>

===Abbreviations===

The following abbreviations and terms are used: 
<table>
<tr class="head">
<th>Term or abbreviation</th>
<th>Definition</th>
</tr>

<tr>
<td>i</td>
<td>Index register number</td>
</tr>

<tr>
<td>
len
n
n|sS
n|i
</td>
<td>
Length, specified as one of:
Number
Number + length of current contents of string buffers
Number + contents of index register i
</td>
</tr>

<tr>
<td>
mode
X'8000'
X'4000'
X'2000'
X'1000'
X'0800'
X'0400'
X'0200'
X'0100'
X'0080'
X'8000'
X'4000'
</td>
<td>
Four-digit hexadecimal number indicating field-loading options:
Begin a new record
Delete the field
Sort or hash key omitted (specified with X'8000')
Delete first occurrence of field
Do not strip leading or trailing blanks
Translation table provided
Load all-zero field as '0'
Strip leading zeroes
Floating-point input
Begin a new record
Delete the field
</td>
</tr>

<tr>
<td>n,m</td>
<td>Decimal integers</td>
</tr>

<tr>
<td>
p
n
n|sS
n|i
</td>
<td>
Position, specified as one of:
Position in current input record
Position in string buffer s
Followed by <code>,</code>: n + contents of index register i is position in current input record 
Followed by <code>*</code>: n is position in index register <var class="term">i</var>
</td>
</tr>

<tr>
<td>s</td>
<td>String buffer number (0 or 1)</td>
</tr>
</table>


The statements are listed in alphabetical order. Replace elements in lowercase. Uppercase elements appear as shown.
<table>
<tr class="head">
<th>File Load statement</th>
<th>Action </th>
</tr>

<tr>
<td>
field=p,len,mode
</td>
<td>Read-and-load-a-field</td>
</tr>

<tr>
<td>
CASE p,len

string1=label1
string2=label2
.
.
.
ENDCASE
</td>
<td>Branch based on string value </td>
</tr>

<tr>
<td>
CFB s,p,len
</td>
<td>Convert from binary</td>
</tr>

<tr>
<td>
CFF s,p,len
</td>
<td>Convert from floating point</td>
</tr>

<tr>
<td>
CFP s,p,len,decimal-places
</td>
<td>Convert from packed decimal</td>
</tr>

<tr>
<td>
CFZ s,p,len,decimal-places
</td>
<td>Convert from zoned decimal</td>
</tr>

<tr>
<td>
D p1,len1=p2,len2,mode
</td>
<td>Read and load field name and value</td>
</tr>

<tr>
<td>
DELETE
</td>
<td>Delete current record</td>
</tr>

<tr>
<td>
DOWN
</td>
<td>Go down one locate level</td>
</tr>

<tr>
<td>
END
</td>
<td>End of file load program</td>
</tr>

<tr>
<td>
ENDF
</td>
<td>End of F loop</td>
</tr>

<tr>
<td>
ENDL
</td>
<td>End of L (locate) loop</td>
</tr>

<tr>
<td>
F label,field=i1,i2
</td>
<td>Read field value from current record</td>
</tr>

<tr>
<td>
G
</td>
<td>Get new input record</td>
</tr>

<tr>
<td>
I i1,p,len,n|i2,m|i3
</td>
<td>Set i1 to (value of data in position p for len bytes) + n + i2 + (m * i3)</td>
</tr>

<tr>
<td>
L s,field=i,label
</td>
<td>Locate field = string buffer value</td>
</tr>

<tr>
<td>
LDC field=value=mode
</td>
<td>Load constant field</td>
</tr>

<tr>
<td>
LOADNULLS ON|OFF
</td>
<td>Load null values</td>
</tr>

<tr>
<td nowrap>
LDRF field=p1,len1,p2,len2,i,mode
</td>
<td>Load repeating field</td>
</tr>

<tr>
<td>
M s,p,len
</td>
<td>Append value to string buffer</td>
</tr>

<tr>
<td>
MC s,value
</td>
<td>Append constant to string buffer</td>
</tr>

<tr>
<td>
P p,len
</td>
<td>Print value</td>
</tr>

<tr>
<td>
Q i
</td>
<td>Print value in index register</td>
</tr>

<tr>
<td>
S s,p,len
</td>
<td>Clear string buffer and load value</td>
</tr>

<tr>
<td>
SC s,value
</td>
<td>Clear string buffer and load constant</td>
</tr>

<tr>
<td>
STOP
</td>
<td>Stop file load program </td>
</tr>

<tr>
<td nowrap>
T label,p1,len,p2,condition 
where condition can be:
<table>
<tr><td>2</td><td>Greater than</td></tr>
<tr><td>4</td><td>Less than</td></tr>
<tr><td>7</td><td>Not equal to</td></tr>
<tr><td>8</td><td>Equal to</td></tr>
<tr><td>11</td><td>Greater than or equal to</td></tr>
<tr><td>13</td><td>Less than or equal to</td></tr>
</table>
</td>
<td>Compare strings and branch conditionally</td>
</tr>

<tr>
<td>
UP
</td>
<td>Go up one locate level </td>
</tr>

<tr>
<td>
XG FLODXTn, c, r, s
</td>
<td>Pass fields to <var>FLOD</var> exit program control</td>
</tr>

<tr>
<td>
#n
</td>
<td>Define label n</td>
</tr>

<tr>
<td>
=label,p,char
</td>
<td>Branch to label, optional comparison of char to input</td>
</tr>

<tr>
<td>
*
</td>
<td>Comment</td>
</tr>
</table>

</div> 

[[Category:File loading and reorganization]]

Customizing functions and translation tables

2015-07-14T18:56:08Z

Tbullock: Forgot the LSTR=YES

==Overview==

User-written SOUL functions are stored in the user function module FUNU. The FUNU module is distributed as a skeletal module containing a table for functions and arguments, and the assembler code for one function. You can list the contents of FUNU using the procedures given in the Rocket Model 204 Installation Guide for your operating system.

The Encoding/Decoding facility uses the translation tables contained in the distributed CDTB module. The <var>$Code</var> and <var>$Decode</var> functions access the translation tables to allow the use of both coded and string values of fields. The contents of the translation tables can be listed by using the procedures listed in the Rocket <var class="product">Model 204</var> Installation Guide for your operating system.

You can store messages and return codes for user-written functions in the MSGU module. 

This page gives the procedures for adding user-written functions to the FUNU module, customizing the translation tables contained in the CDTB module, and adding messages to MSGU.

If you are migrating to 31-bit or multiprocessing environments, review the conversion considerations summarized in [[#Converting user-written functions|Converting user-written functions]]. 

For general directions on assembly and link-editing, see the Rocket <var class="product">Model 204</var> Installation Guide for your operating system. 

==Adding functions to the FUNU module==

You can add user-written functions to the FUNU module before FUNU is assembled and linked into <var class="product">Model 204</var>. Reassembly and relinking is required whenever you migrate to another release of <var class="product">Model 204</var>.

To add functions to the FUNU module:
<ol>
<li>Label the function table in the FUNU source code FUNUTAB. </li>

<li>End the function table in the FUNU source code with <code>DC X'FFFF'</code>.

The location of the function table in the code is not significant.
</li>

<li>Make the new function available to the <var class="product">Model 204</var> SOUL compiler by adding an entry to the function table using the FN macro:
FN function-name, R-type, (A-type [, A-type]...),ROUTINE=

Where:
<ul>
<li><var class="term">function-name</var> specifies a unique 1- to 7-character name of the function without the leading <code>$</code>. Spaces or special characters are not allowed.

User-written functions must not duplicate the name of Rocket Software functions. A list of Rocket Software functions is given in [[SOUL $functions]].</li>

<li><var class="term">R-type</var> represents the type of value returned from the function. Only one value can be returned. <code>S</code> represents a string value. <code>N</code> represents a numeric value. </li>

<li><var class="term">A-type</var> describes the type of argument value. More than one argument can be specified. <code>S</code> represents a string value. <code>N</code> represents a numeric value. </li>


In the following example, <code>$SEP</code> receives three string arguments and returns a string value:
FN SEP,S,(S,S,S)

</li>

<li><var class="term">ROUTINE=</var> identifies the name on the ENTER macro of the routine that actually implements the function. This allows the name of the $function (the name on the FN macro) to be greater than 7 characters.</li>
For example, one of the MQ/204 $functions, $MQ_FIND_QUEUE_ENTITY, has these two entries (not in FUNU) for FN and ENTER:

FN MQ_FIND_QUEUE_ENTITY,S,(S,S),MP=OK,ROUTINE=$MQFNDQ
...
$MQFNDQ ENTER ZMODE=64
assembly language code for the function
LEAVESTR

</li>
</ul>

<li>Code the function (as described in [[#Coding a function|Coding a function]].</li>
</ol>

==Coding a function==
===Coding conventions===

The following conventions are required for coding a user-written function:
<ul>
<li>Begin the function code with:
$name ENTER
</li>

<li>End the function code with:
POOL
</li>

<li>Observe the following register conventions (correspondence between Rocket Software mnemonic names and IBM general registers is printed at the beginning of the module in the expansion of the STARTS macro):
<ul>
<li>Registers RC, R6, PD, and RL must not be modified.</li>

<li>Registers T1 through T5 and R1 through R5 can be used as work registers.</li>

<li>Registers R1 through R5 are somewhat more permanent. </li>

<li>Use BUF1 and BUF2 (260 bytes each) as buffers (doubleword aligned). </li>

<li>Use string, numeric, or omitted arguments. </li>
</ul></li>
</ul>

===String arguments===

If the <var class="term">n</var>th argument is type <var>S</var>, you can move the argument into a work area by using the following code. Registers R1 through R4 are used by this sequence:
ARG n
L R2,4(X1)
CCALL RTSTRL
EX R2,FOO
STC R2,BUF1
.
.
FOO MVC BUF1(0),0(R1)
.

<ul>
<li>The <code>ARG</code> macro returns the VTBL pointer to the <var class="term">n</var>th argument in X1.</li>

<li>The <code>RTSTRL</code> routine sets <code>R2</code> to the length of the string, and it sets <code>R1</code> to address-1 of the string.</li>

<li>The length of the string is given by register <code>R2</code>.</li>

<li>The string is moved to <code>BUF1</code>, starting at location <code>BUF1 + 1</code>.</li>

<li>The string length is moved to location <code>BUF1</code>. </li>
</ul>

===Numeric arguments===

If the <var class="term">n</var>th argument of a function is type <var>N</var>, you can obtain the argument in floating-point form or binary integer form (truncated or rounded) using registers R1 through R3, as follows: 
ARG n
LA R3,x
CCALL INTEG
.
.
.


Where:
<ul>
<li><var class="term">x</var> = 0, if a truncated value is required.</li>

<li><var class="term">x</var> = <var class="term">value,</var> if a rounded value is required. </li>
</ul>

After this sequence, F0 contains the original floating-point value. If the number is valid, R1 contains the integer portion of the number as a binary value and R2 is zero. If the number is invalid, R1 is zero and R2 is nonzero.

===Omitted arguments===

When writing a call to a function, you can omit an argument, as follows:
$Read( )
$Substr(NAME,,5)


Where:
<ul>
<li>If the omitted argument is type <var>S</var>, the value of the argument defaults to a null string.</li>

<li>If the argument is type <var>N</var>, the value defaults to zero. </li>
</ul>

====NOARG option====

You can specify the <var>NOARG</var> option on the ARG macro in the event that an argument is omitted. When <var>NOARG</var> is used, the code branches to the location indicated by the <var>NOARG</var> option. For example:
ARG n,NOARG=ALLDONE
L R2,4(X1)
CCALL RTST
.
.
.
CCALL DKRL
ALLDONE DS OH
.
.
.
LEAVESTR


You can also specify the following, which returns control to the next sequential instruction after the <var>ARG</var> statement:
NOARG = *


===Using the ENTER macro to allocate working storage===

You can use the <var>VARS</var> argument of the ENTER macro to define stack variables for working storage unique to each user-written function. This method of allocating storage is preferable to STORAGE, GETMAIN, and FREEMAIN instructions. Using the ENTER macro avoids the possibility of causing Online waits or having all users share the same storage.

====Syntax for ENTER VARS====
ENTER VARS = (, X
(varname1, varlength1), comments X
(varname2, varlength2), comments X
(varname3, varlength3), comments X
.
.
.
), AMODE=n


You must initialize each of these variables.

====Routines available for user written $functions====

There are CCALL entry points for: DATE, DATE3, and DATE4. All routines must be called with T1 pointing to a 26-byte answer area. Rocket Software recommends that you allocate the answer area using the <code>VARS=(name, len)</code> pushdown list variable of the ENTER macro.
The following table lists how the current date and time is stored in the area with this format:
<table>
<caption>Formats used to store the date routines</caption>
<tr class="head">
<th>Code entry point</th>
<th>Format used for storing...</th>
</tr>

<tr>
<td>
DATE
</td>
<td>
'YY.DDD MON DD HH.MM.SS'
</td>
</tr>

<tr>
<td>
DATE3
</td>
<td>
'CYY.DDD MON DD HH.MM.SS'
</td>
</tr>

<tr>
<td>
DATE4
</td>
<td>
'YYYY.DDD MON DD HH.MM.SS'
</td>
</tr>
</table>

All registers are returned intact with the exception of the DATE call. The DATE call changes only the T4 register, returning the number representing the current month (1-12).

Note that there are double SPACEs before and after the "MON DD".

===Return values===

Functions can return a string or a numeric value. The following coding considerations apply:
<ul>
<li>To return a string value, end the function routine by doing the following:
<ol>
<li>Load R1 with a pointer to the location of the result string minus one.</li>

<li>Load R2 with the length of the result string.</li>

<li>Issue the LEAVESTR macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
</ol></li>

<li>To return a numeric value, end the function routine in one of the following ways, depending on how the result is computed:
<ul>
<li>For an integer result, end the code end with the following:
<ol>
<li>Load the binary integer into R1.</li>

<li>Zero R2.</li>

<li>Issue the LEAVENUM macro just before POOL or LTORG.</li>
</ol></li>

<li>For a floating-point result, end the code with the following:
<ol>
<li>Load F0 with the long floating-point number.</li>

<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>
</ol></li>

</ul></li>

<li>To return a longstring value, end the function routine by doing the following:
<ol>
<li>Code LSTR=YES on the end of the FN macro, along with the S for string output.</li>
<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>
<li>Load R2 with the length of the result longstring.</li>
<li>Issue the LEAVELST macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
</ol></li>

<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>

</ul>

===Coding messages===

You can add messages and codes specific to user-written functions by adding EDEF message lines to the MSGU module. These are referenced in your functions by invoking the ERROR macro.

To code and activate messages and return codes:
<ol>
<li>Add EDEF statements to MSGU as needed in place of the dummy EDEF in the distributed module.</li>

<li>Add ERROR macros to your functions, referring to messages in MSGU by message number as follows:
ERROR errnum,OPT=USER
</li>

<li>Reassemble MSGU and FUNU.</li>

<li>Relink the <var class="product">Model 204</var> modules (for example BATCH204, ONLINE) in which MSGU and FUNU are included.</li>
</ol>

====EDEF statements in MSGU====

Each EDEF statement defines a message. 

=====EDEF statement syntax=====
EDEF msgno, aaaa, class, batchrc, ssss, text


Where:
<ul>
<li><var class="term">msgno</var> denotes message number.</li>

<li><var class="term">aaaa</var> denotes action bits controlling output, snap generation, register pointers, and so on.</li>

<li><var class="term">class</var> (E, I, or P) specifies batch and Online return code requirements.</li>

<li><var class="term">batchrc</var> specifies batch return code.</li>

<li><var class="term">ssss</var> denotes snap bits controlling contents of snaps and dumps.</li>

<li><var class="term">text</var> contains message text, which can contain %variables passed by invocation of the ERROR macro.</li>
</ul>

For complete details on these EDEF arguments, refer to the internal documentation in the MSGU listing. 

==Encoding/Decoding facility==

The <var class="product">Model 204</var> SOUL <var>[[$Code]]</var> and <var>[[$Decode]]</var> functions provide the capacity to operate with both coded and string values of fields.


===CDTB module===

Define code tables in the CDTB module, which you must include in any load module needed to support the <var>$Code</var> and <var>$Decode</var> functions (usually with BATCH204 and ONLINE configurations). 

CDTB is an assembly language program consisting of:
<ul>
<li>Three macros used to define each table distributed in source code form</li>

<li>Comments explaining the macros</li>

<li>CSECT statement</li>

<li>Three sample tables</li>

<li>END statement </li>
</ul>

The macros contained in the CDTB module are:
<ul>
<li>CODETABL
CODETABL id, length 

Where:
<ul>
<li><var class="term">id</var> is a 1- to 8-character string, not enclosed in quotation marks, used to identify the table.</li>

<li><var class="term">length</var> is the length of the longest code found in the table. </li>
</ul>

The CODETABL macro builds a table header that consists of a pointer to the next table, the table identifier, the number of entries in the table, and the length of the longest code. Each table defined must specify one CODETABL macro.</li>

<li>CODE
CODE code, 'string'


Where:
<ul>
<li><var class="term">code</var> is the code not enclosed in quotation marks and not longer than the length specified in the previous CODETABL macro.</li>

<li><var class="term">string</var> is the string associated with the code and is enclosed in quotation marks. The string can have up to 255 characters. </li>
</ul>

The CODE macro builds one entry that consists of the code, the string length, and the string value. The CODE macro must be used individually for each entry in the table. </li>

<li>ENDTAB
ENDTAB

ENDTAB requires no operands and indicates the end of the current table. One ENDTAB macro is required for each table. ENDTAB completes the definition of the table by: 
<ul>
<li>Returning to the header created by the previous CODETABL macro</li>

<li>Updating the information about the pointer to the next table</li>

<li>Updating the number of entries in the table just defined</li>

<li>Setting up information to start the next table or to mark the end of all tables </li>
</ul></li>
</ul>

===Customizing the sample translation tables===

To modify the distributed sample translation tables (refer also to the Rocket <var class="product">Model 204</var> Installation Guide for your operating system): 
<ol>
<li>List CDTB with its sequence numbers.</li>

<li>Replace the sample tables by using an appropriate operating system utility program.</li>

<li>Assemble the program.</li>

<li>Link the object modules into the appropriate <var class="product">Model 204</var> load modules.</li>
</ol>

===Modifying translation tables===

To make additions, deletions, or changes to translation tables (refer also to the Rocket <var class="product">Model 204</var> Installation Guide for your operating system): 
<ol>
<li>Modify the source code.</li>
<li>Assemble the source code.</li>
<li>Link-edit the new CDTB module into the appropriate <var class="product">Model 204</var> load modules.
</li>
</ol>

===Sizing the CDTB module===

The size of the CDTB module depends on the tables defined. If tables are very large, CDTB might require a significant amount of storage, resulting in an adjustment to the REGION size.

Each table entry requires:
Number of bytes in the longest code + 1 (for string length) + the number of bytes in the string + 1


32 bytes per table is required overhead for header information.

==Converting user-written functions==

User-written $functions may need to be modified if you are migrating to 31-bit or multi-processing environment. While Rocket Software generally discourages customers from coding $functions that have extensive dependencies on <var class="product">Model 204</var> internal data structures and algorithms, some customers have found it necessary to do so. These conversion notes describe the changes required for the conversion of most $functions.
Note:
These sections do not provide complete descriptions of all internal data structure and algorithm changes that have been made to <var class="product">Model 204</var>; nor are they to be construed as official sanction on Rocket Software's part of the use of any specific interfaces or of the dependency on any specific data structure or algorithm. All such interfaces, data structures, and algorithms remain subject to change without notice.
<ul>
<li>[[#Additional requirements for systems using 31-bit architecture|Additional requirements for systems using 31-bit architecture]] applies to all sites that use 31-bit architecture. </li>

<li>[[#Additional requirements for MP/204 (multiprocessing)|Additional requirements for MP/204 (multiprocessing)]] applies to users of MP/204 (multiprocessing). </li>
</ul>

===Coding requirements for all operating systems===

Observe the following coding requirements for all operating systems:
<ul>
<li><var class="product">Model 204</var> runs in 64-bit mode and requires all registers to be saved and restored using the grande versions of the assembly instructions STM (Store Multiple) and LM (Load Multiple). All user-written functions must be reviewed and modified to use STMG and LMG instructions. </li>

<li>Change $functions that refer to KX or KY as follows:
<ul>
<li>Remove X,Y arguments from the KOMMS macro.</li>

<li>Code the new FSA macro with the same X,Y arguments that were present on the KOMMS macro.</li>

<li>Modify references to fields in KX or KY to use a different base register from the KOMM base register as follows:

L reg,KJFLKX
USING KX,reg
refer to KX or KY fields
DROP reg
</li>
</ul></li>

<li>From the CCALL MOVEIN routine, remove CCALL. This places the code inline. By expanding the code, efficiency is improved. The input and output are the same as before. However, you might have to add pool statements to the macro, since the offset points to a pool.</li>

<li>Some KOMM fields have been moved from KA-KD to KZ. While user-written $functions should not generally reference these fields, those that do need to address KZ as follows:
L reg, KBPKZ
USING KZ,reg
refer to KZ fields
DROP reg
</li>

<li>The CSAVE or IOSAVE macros replace the SETAMODE macro in the MACLIB.</li>

<li>The AMODE parameter of the ENTER macro is ignored. The CCALL, ENTER, and KARTN sequences no longer cause switches in addressing mode.</li>

<li>The XAMODE macros are now obsolete and have been deleted from Rocket Software-delivered MACLIBs. Consequently, it is no longer necessary to maintain XAMODE$U. </li>

<li>Reassemble FUNU and FUNUUG. </li>
</ul>

===Additional requirements for systems using 31-bit architecture===

All code receives control in 31-bit mode. See IBM z/OS/XA Principles of Operation for differences between 24-bit and 31-bit mode operation:
<ul>
<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>

<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code prior to adding KUPVT or KUPST. </li>

<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>

<li>The <var>NOARG</var> parameter (described in [[#NOARG option|NOARG option]]) is required for <var>ARG</var> statements in 31-bit mode.</li>

<li>You cannot use the CCALL macro in 24-bit mode. </li>

<li>For users of the multiple KOMM feature:
<ul>
<li>If the $function switches to z/OS register conventions, RC might at some point no longer be equal to KOMM. Use the following code to locate KOMM:
CURROSW REG=x
LLGF y,OSWPUK-OSW(,x)
</li>

<li>In ESA systems, each user's KOMM is allocated in 31-bit storage.

(See the discussion of MP system parameters in [[Performance monitoring and tuning]]). 
</li>
</ul></li>
</ul>

===Additional requirements for MP/204 (multiprocessing)===
<ul>
<li>The FN macro has an MP argument, which defaults to <code>NO</code>. Other legal values are <code>OK</code> and <code>YES</code>. When the FN macro specifies <code>MP=NO</code>, the $function is guaranteed to execute in the maintask.</li>

<li>When a $function is invoked that specifies <code>MP=OK</code>, that $function might execute in one of the MP subtasks, depending on whether <var class="product">Model 204</var> is running in parallel a section of code that contains it. If so, the $function is eligible to execute in a subtask.</li>

<li>When a $function is invoked that specifies <code>MP=YES</code>, that $function executes in one of the MP subtasks, regardless of whether the section of code within which it is contained is running in parallel. Usually, only $functions with relatively long pathlength should specify <code>MP=YES</code>, because the cost of switching from the maintask to a subtask can be in the thousands of instructions. Because the exact cost of switching tasks depends on how busy the subtasks and the maintask are, measurements should be made in marginal circumstances.</li>

<li>$functions that are eligible for subtask execution actually execute on one of the subtasks under either of the following conditions:
<ul>
<li><code>SCHDOPT=X'02'</code> is specified.</li>

<li>The section of code in which the $function is coded is executed at a time when other users are on the scheduler's READY queue. </li>
</ul></li>

<li>$functions that specify <code>MP=OK</code> or <code>MP=YES</code>:
<ul>
<li>Are not guaranteed to always execute in the same subtask when <var>[[NMPSUBS parameter|NMPSUBS]]</var> is greater than 1. </li>

<li>Must be re-entrant.</li>

<li>Must not use any internal <var class="product">Model 204</var> interfaces that require maintask execution, for example, APUT, DKIW, and CENQxxx.</li>
</ul></li>

<li><code>MP=OK</code> and <code>MP=YES</code> have no effect when the MP feature is not in use (<code>NMPSUBS=0</code>).</li>
</ul>

===Additional requirements for zIIP processing===
If Model 204 runs with [[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|zIIP processors]], an <code>MP=YES</code>, <code>MP=OK</code>, <code>MP=ZYES</code>, or <code>MP=ZOK</code> setting in the FN macro might cause a $function to be executed on the zIIP subtask, which does not allow an SVC instruction. Customers planning to use zIIP processing must do either of these:
<ul>
<li>Inspect any user-written $functions for non-tolerant code. This is code that uses an explicit SVC instruction or requests system services that might use an SVC, like BSAM, VTAM, or task-mode z/OS macros, or macros that are not allowed to be invoked on an SRB (enclave Service Request Block, the environment when a $function is executed on a zIIP processor). Bracket this code with <code>SRBMODE OFF</code> and <code>SRBMODE ON</code>. </li>

<li>Specify <code>MP=NO</code> (the default) or no <var>MP</var> setting at all in the FN macro to cause $functions to run on the maintask and not on a zIIP SRB. Any other value for <var>MP</var> enables $functions to run on zIIP subtasks. </li>
</ul>
Note: It is not always obvious if code may or may not run on a zIIP subtask. Even if all explicit SVCs and non-task-mode system macros issued by Model 204 have been identified and bracketed, some may be issued implicitly by z/OS or other services, so user testing is important. 

[[Category:System management]]
[[Category:Model 204 operational issues]]

Customizing functions and translation tables

2015-07-14T18:46:44Z

Tbullock: Oops messed up the li and ol nesting.

==Overview==

User-written SOUL functions are stored in the user function module FUNU. The FUNU module is distributed as a skeletal module containing a table for functions and arguments, and the assembler code for one function. You can list the contents of FUNU using the procedures given in the Rocket Model 204 Installation Guide for your operating system.

The Encoding/Decoding facility uses the translation tables contained in the distributed CDTB module. The <var>$Code</var> and <var>$Decode</var> functions access the translation tables to allow the use of both coded and string values of fields. The contents of the translation tables can be listed by using the procedures listed in the Rocket <var class="product">Model 204</var> Installation Guide for your operating system.

You can store messages and return codes for user-written functions in the MSGU module. 

This page gives the procedures for adding user-written functions to the FUNU module, customizing the translation tables contained in the CDTB module, and adding messages to MSGU.

If you are migrating to 31-bit or multiprocessing environments, review the conversion considerations summarized in [[#Converting user-written functions|Converting user-written functions]]. 

For general directions on assembly and link-editing, see the Rocket <var class="product">Model 204</var> Installation Guide for your operating system. 

==Adding functions to the FUNU module==

You can add user-written functions to the FUNU module before FUNU is assembled and linked into <var class="product">Model 204</var>. Reassembly and relinking is required whenever you migrate to another release of <var class="product">Model 204</var>.

To add functions to the FUNU module:
<ol>
<li>Label the function table in the FUNU source code FUNUTAB. </li>

<li>End the function table in the FUNU source code with <code>DC X'FFFF'</code>.

The location of the function table in the code is not significant.
</li>

<li>Make the new function available to the <var class="product">Model 204</var> SOUL compiler by adding an entry to the function table using the FN macro:
FN function-name, R-type, (A-type [, A-type]...),ROUTINE=

Where:
<ul>
<li><var class="term">function-name</var> specifies a unique 1- to 7-character name of the function without the leading <code>$</code>. Spaces or special characters are not allowed.

User-written functions must not duplicate the name of Rocket Software functions. A list of Rocket Software functions is given in [[SOUL $functions]].</li>

<li><var class="term">R-type</var> represents the type of value returned from the function. Only one value can be returned. <code>S</code> represents a string value. <code>N</code> represents a numeric value. </li>

<li><var class="term">A-type</var> describes the type of argument value. More than one argument can be specified. <code>S</code> represents a string value. <code>N</code> represents a numeric value. </li>


In the following example, <code>$SEP</code> receives three string arguments and returns a string value:
FN SEP,S,(S,S,S)

</li>

<li><var class="term">ROUTINE=</var> identifies the name on the ENTER macro of the routine that actually implements the function. This allows the name of the $function (the name on the FN macro) to be greater than 7 characters.</li>
For example, one of the MQ/204 $functions, $MQ_FIND_QUEUE_ENTITY, has these two entries (not in FUNU) for FN and ENTER:

FN MQ_FIND_QUEUE_ENTITY,S,(S,S),MP=OK,ROUTINE=$MQFNDQ
...
$MQFNDQ ENTER ZMODE=64
assembly language code for the function
LEAVESTR

</li>
</ul>

<li>Code the function (as described in [[#Coding a function|Coding a function]].</li>
</ol>

==Coding a function==
===Coding conventions===

The following conventions are required for coding a user-written function:
<ul>
<li>Begin the function code with:
$name ENTER
</li>

<li>End the function code with:
POOL
</li>

<li>Observe the following register conventions (correspondence between Rocket Software mnemonic names and IBM general registers is printed at the beginning of the module in the expansion of the STARTS macro):
<ul>
<li>Registers RC, R6, PD, and RL must not be modified.</li>

<li>Registers T1 through T5 and R1 through R5 can be used as work registers.</li>

<li>Registers R1 through R5 are somewhat more permanent. </li>

<li>Use BUF1 and BUF2 (260 bytes each) as buffers (doubleword aligned). </li>

<li>Use string, numeric, or omitted arguments. </li>
</ul></li>
</ul>

===String arguments===

If the <var class="term">n</var>th argument is type <var>S</var>, you can move the argument into a work area by using the following code. Registers R1 through R4 are used by this sequence:
ARG n
L R2,4(X1)
CCALL RTSTRL
EX R2,FOO
STC R2,BUF1
.
.
FOO MVC BUF1(0),0(R1)
.

<ul>
<li>The <code>ARG</code> macro returns the VTBL pointer to the <var class="term">n</var>th argument in X1.</li>

<li>The <code>RTSTRL</code> routine sets <code>R2</code> to the length of the string, and it sets <code>R1</code> to address-1 of the string.</li>

<li>The length of the string is given by register <code>R2</code>.</li>

<li>The string is moved to <code>BUF1</code>, starting at location <code>BUF1 + 1</code>.</li>

<li>The string length is moved to location <code>BUF1</code>. </li>
</ul>

===Numeric arguments===

If the <var class="term">n</var>th argument of a function is type <var>N</var>, you can obtain the argument in floating-point form or binary integer form (truncated or rounded) using registers R1 through R3, as follows: 
ARG n
LA R3,x
CCALL INTEG
.
.
.


Where:
<ul>
<li><var class="term">x</var> = 0, if a truncated value is required.</li>

<li><var class="term">x</var> = <var class="term">value,</var> if a rounded value is required. </li>
</ul>

After this sequence, F0 contains the original floating-point value. If the number is valid, R1 contains the integer portion of the number as a binary value and R2 is zero. If the number is invalid, R1 is zero and R2 is nonzero.

===Omitted arguments===

When writing a call to a function, you can omit an argument, as follows:
$Read( )
$Substr(NAME,,5)


Where:
<ul>
<li>If the omitted argument is type <var>S</var>, the value of the argument defaults to a null string.</li>

<li>If the argument is type <var>N</var>, the value defaults to zero. </li>
</ul>

====NOARG option====

You can specify the <var>NOARG</var> option on the ARG macro in the event that an argument is omitted. When <var>NOARG</var> is used, the code branches to the location indicated by the <var>NOARG</var> option. For example:
ARG n,NOARG=ALLDONE
L R2,4(X1)
CCALL RTST
.
.
.
CCALL DKRL
ALLDONE DS OH
.
.
.
LEAVESTR


You can also specify the following, which returns control to the next sequential instruction after the <var>ARG</var> statement:
NOARG = *


===Using the ENTER macro to allocate working storage===

You can use the <var>VARS</var> argument of the ENTER macro to define stack variables for working storage unique to each user-written function. This method of allocating storage is preferable to STORAGE, GETMAIN, and FREEMAIN instructions. Using the ENTER macro avoids the possibility of causing Online waits or having all users share the same storage.

====Syntax for ENTER VARS====
ENTER VARS = (, X
(varname1, varlength1), comments X
(varname2, varlength2), comments X
(varname3, varlength3), comments X
.
.
.
), AMODE=n


You must initialize each of these variables.

====Routines available for user written $functions====

There are CCALL entry points for: DATE, DATE3, and DATE4. All routines must be called with T1 pointing to a 26-byte answer area. Rocket Software recommends that you allocate the answer area using the <code>VARS=(name, len)</code> pushdown list variable of the ENTER macro.
The following table lists how the current date and time is stored in the area with this format:
<table>
<caption>Formats used to store the date routines</caption>
<tr class="head">
<th>Code entry point</th>
<th>Format used for storing...</th>
</tr>

<tr>
<td>
DATE
</td>
<td>
'YY.DDD MON DD HH.MM.SS'
</td>
</tr>

<tr>
<td>
DATE3
</td>
<td>
'CYY.DDD MON DD HH.MM.SS'
</td>
</tr>

<tr>
<td>
DATE4
</td>
<td>
'YYYY.DDD MON DD HH.MM.SS'
</td>
</tr>
</table>

All registers are returned intact with the exception of the DATE call. The DATE call changes only the T4 register, returning the number representing the current month (1-12).

Note that there are double SPACEs before and after the "MON DD".

===Return values===

Functions can return a string or a numeric value. The following coding considerations apply:
<ul>
<li>To return a string value, end the function routine by doing the following:
<ol>
<li>Load R1 with a pointer to the location of the result string minus one.</li>

<li>Load R2 with the length of the result string.</li>

<li>Issue the LEAVESTR macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
</ol></li>

<li>To return a numeric value, end the function routine in one of the following ways, depending on how the result is computed:
<ul>
<li>For an integer result, end the code end with the following:
<ol>
<li>Load the binary integer into R1.</li>

<li>Zero R2.</li>

<li>Issue the LEAVENUM macro just before POOL or LTORG.</li>
</ol></li>

<li>For a floating-point result, end the code with the following:
<ol>
<li>Load F0 with the long floating-point number.</li>

<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>
</ol></li>

</ul></li>

<li>To return a longstring value, end the function routine by doing the following:
<ol>
<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>
<li>Load R2 with the length of the result longstring.</li>
<li>Issue the LEAVELST macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
</ol></li>

<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>

</ul>

===Coding messages===

You can add messages and codes specific to user-written functions by adding EDEF message lines to the MSGU module. These are referenced in your functions by invoking the ERROR macro.

To code and activate messages and return codes:
<ol>
<li>Add EDEF statements to MSGU as needed in place of the dummy EDEF in the distributed module.</li>

<li>Add ERROR macros to your functions, referring to messages in MSGU by message number as follows:
ERROR errnum,OPT=USER
</li>

<li>Reassemble MSGU and FUNU.</li>

<li>Relink the <var class="product">Model 204</var> modules (for example BATCH204, ONLINE) in which MSGU and FUNU are included.</li>
</ol>

====EDEF statements in MSGU====

Each EDEF statement defines a message. 

=====EDEF statement syntax=====
EDEF msgno, aaaa, class, batchrc, ssss, text


Where:
<ul>
<li><var class="term">msgno</var> denotes message number.</li>

<li><var class="term">aaaa</var> denotes action bits controlling output, snap generation, register pointers, and so on.</li>

<li><var class="term">class</var> (E, I, or P) specifies batch and Online return code requirements.</li>

<li><var class="term">batchrc</var> specifies batch return code.</li>

<li><var class="term">ssss</var> denotes snap bits controlling contents of snaps and dumps.</li>

<li><var class="term">text</var> contains message text, which can contain %variables passed by invocation of the ERROR macro.</li>
</ul>

For complete details on these EDEF arguments, refer to the internal documentation in the MSGU listing. 

==Encoding/Decoding facility==

The <var class="product">Model 204</var> SOUL <var>[[$Code]]</var> and <var>[[$Decode]]</var> functions provide the capacity to operate with both coded and string values of fields.


===CDTB module===

Define code tables in the CDTB module, which you must include in any load module needed to support the <var>$Code</var> and <var>$Decode</var> functions (usually with BATCH204 and ONLINE configurations). 

CDTB is an assembly language program consisting of:
<ul>
<li>Three macros used to define each table distributed in source code form</li>

<li>Comments explaining the macros</li>

<li>CSECT statement</li>

<li>Three sample tables</li>

<li>END statement </li>
</ul>

The macros contained in the CDTB module are:
<ul>
<li>CODETABL
CODETABL id, length 

Where:
<ul>
<li><var class="term">id</var> is a 1- to 8-character string, not enclosed in quotation marks, used to identify the table.</li>

<li><var class="term">length</var> is the length of the longest code found in the table. </li>
</ul>

The CODETABL macro builds a table header that consists of a pointer to the next table, the table identifier, the number of entries in the table, and the length of the longest code. Each table defined must specify one CODETABL macro.</li>

<li>CODE
CODE code, 'string'


Where:
<ul>
<li><var class="term">code</var> is the code not enclosed in quotation marks and not longer than the length specified in the previous CODETABL macro.</li>

<li><var class="term">string</var> is the string associated with the code and is enclosed in quotation marks. The string can have up to 255 characters. </li>
</ul>

The CODE macro builds one entry that consists of the code, the string length, and the string value. The CODE macro must be used individually for each entry in the table. </li>

<li>ENDTAB
ENDTAB

ENDTAB requires no operands and indicates the end of the current table. One ENDTAB macro is required for each table. ENDTAB completes the definition of the table by: 
<ul>
<li>Returning to the header created by the previous CODETABL macro</li>

<li>Updating the information about the pointer to the next table</li>

<li>Updating the number of entries in the table just defined</li>

<li>Setting up information to start the next table or to mark the end of all tables </li>
</ul></li>
</ul>

===Customizing the sample translation tables===

To modify the distributed sample translation tables (refer also to the Rocket <var class="product">Model 204</var> Installation Guide for your operating system): 
<ol>
<li>List CDTB with its sequence numbers.</li>

<li>Replace the sample tables by using an appropriate operating system utility program.</li>

<li>Assemble the program.</li>

<li>Link the object modules into the appropriate <var class="product">Model 204</var> load modules.</li>
</ol>

===Modifying translation tables===

To make additions, deletions, or changes to translation tables (refer also to the Rocket <var class="product">Model 204</var> Installation Guide for your operating system): 
<ol>
<li>Modify the source code.</li>
<li>Assemble the source code.</li>
<li>Link-edit the new CDTB module into the appropriate <var class="product">Model 204</var> load modules.
</li>
</ol>

===Sizing the CDTB module===

The size of the CDTB module depends on the tables defined. If tables are very large, CDTB might require a significant amount of storage, resulting in an adjustment to the REGION size.

Each table entry requires:
Number of bytes in the longest code + 1 (for string length) + the number of bytes in the string + 1


32 bytes per table is required overhead for header information.

==Converting user-written functions==

User-written $functions may need to be modified if you are migrating to 31-bit or multi-processing environment. While Rocket Software generally discourages customers from coding $functions that have extensive dependencies on <var class="product">Model 204</var> internal data structures and algorithms, some customers have found it necessary to do so. These conversion notes describe the changes required for the conversion of most $functions.
Note:
These sections do not provide complete descriptions of all internal data structure and algorithm changes that have been made to <var class="product">Model 204</var>; nor are they to be construed as official sanction on Rocket Software's part of the use of any specific interfaces or of the dependency on any specific data structure or algorithm. All such interfaces, data structures, and algorithms remain subject to change without notice.
<ul>
<li>[[#Additional requirements for systems using 31-bit architecture|Additional requirements for systems using 31-bit architecture]] applies to all sites that use 31-bit architecture. </li>

<li>[[#Additional requirements for MP/204 (multiprocessing)|Additional requirements for MP/204 (multiprocessing)]] applies to users of MP/204 (multiprocessing). </li>
</ul>

===Coding requirements for all operating systems===

Observe the following coding requirements for all operating systems:
<ul>
<li><var class="product">Model 204</var> runs in 64-bit mode and requires all registers to be saved and restored using the grande versions of the assembly instructions STM (Store Multiple) and LM (Load Multiple). All user-written functions must be reviewed and modified to use STMG and LMG instructions. </li>

<li>Change $functions that refer to KX or KY as follows:
<ul>
<li>Remove X,Y arguments from the KOMMS macro.</li>

<li>Code the new FSA macro with the same X,Y arguments that were present on the KOMMS macro.</li>

<li>Modify references to fields in KX or KY to use a different base register from the KOMM base register as follows:

L reg,KJFLKX
USING KX,reg
refer to KX or KY fields
DROP reg
</li>
</ul></li>

<li>From the CCALL MOVEIN routine, remove CCALL. This places the code inline. By expanding the code, efficiency is improved. The input and output are the same as before. However, you might have to add pool statements to the macro, since the offset points to a pool.</li>

<li>Some KOMM fields have been moved from KA-KD to KZ. While user-written $functions should not generally reference these fields, those that do need to address KZ as follows:
L reg, KBPKZ
USING KZ,reg
refer to KZ fields
DROP reg
</li>

<li>The CSAVE or IOSAVE macros replace the SETAMODE macro in the MACLIB.</li>

<li>The AMODE parameter of the ENTER macro is ignored. The CCALL, ENTER, and KARTN sequences no longer cause switches in addressing mode.</li>

<li>The XAMODE macros are now obsolete and have been deleted from Rocket Software-delivered MACLIBs. Consequently, it is no longer necessary to maintain XAMODE$U. </li>

<li>Reassemble FUNU and FUNUUG. </li>
</ul>

===Additional requirements for systems using 31-bit architecture===

All code receives control in 31-bit mode. See IBM z/OS/XA Principles of Operation for differences between 24-bit and 31-bit mode operation:
<ul>
<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>

<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code prior to adding KUPVT or KUPST. </li>

<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>

<li>The <var>NOARG</var> parameter (described in [[#NOARG option|NOARG option]]) is required for <var>ARG</var> statements in 31-bit mode.</li>

<li>You cannot use the CCALL macro in 24-bit mode. </li>

<li>For users of the multiple KOMM feature:
<ul>
<li>If the $function switches to z/OS register conventions, RC might at some point no longer be equal to KOMM. Use the following code to locate KOMM:
CURROSW REG=x
LLGF y,OSWPUK-OSW(,x)
</li>

<li>In ESA systems, each user's KOMM is allocated in 31-bit storage.

(See the discussion of MP system parameters in [[Performance monitoring and tuning]]). 
</li>
</ul></li>
</ul>

===Additional requirements for MP/204 (multiprocessing)===
<ul>
<li>The FN macro has an MP argument, which defaults to <code>NO</code>. Other legal values are <code>OK</code> and <code>YES</code>. When the FN macro specifies <code>MP=NO</code>, the $function is guaranteed to execute in the maintask.</li>

<li>When a $function is invoked that specifies <code>MP=OK</code>, that $function might execute in one of the MP subtasks, depending on whether <var class="product">Model 204</var> is running in parallel a section of code that contains it. If so, the $function is eligible to execute in a subtask.</li>

<li>When a $function is invoked that specifies <code>MP=YES</code>, that $function executes in one of the MP subtasks, regardless of whether the section of code within which it is contained is running in parallel. Usually, only $functions with relatively long pathlength should specify <code>MP=YES</code>, because the cost of switching from the maintask to a subtask can be in the thousands of instructions. Because the exact cost of switching tasks depends on how busy the subtasks and the maintask are, measurements should be made in marginal circumstances.</li>

<li>$functions that are eligible for subtask execution actually execute on one of the subtasks under either of the following conditions:
<ul>
<li><code>SCHDOPT=X'02'</code> is specified.</li>

<li>The section of code in which the $function is coded is executed at a time when other users are on the scheduler's READY queue. </li>
</ul></li>

<li>$functions that specify <code>MP=OK</code> or <code>MP=YES</code>:
<ul>
<li>Are not guaranteed to always execute in the same subtask when <var>[[NMPSUBS parameter|NMPSUBS]]</var> is greater than 1. </li>

<li>Must be re-entrant.</li>

<li>Must not use any internal <var class="product">Model 204</var> interfaces that require maintask execution, for example, APUT, DKIW, and CENQxxx.</li>
</ul></li>

<li><code>MP=OK</code> and <code>MP=YES</code> have no effect when the MP feature is not in use (<code>NMPSUBS=0</code>).</li>
</ul>

===Additional requirements for zIIP processing===
If Model 204 runs with [[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|zIIP processors]], an <code>MP=YES</code>, <code>MP=OK</code>, <code>MP=ZYES</code>, or <code>MP=ZOK</code> setting in the FN macro might cause a $function to be executed on the zIIP subtask, which does not allow an SVC instruction. Customers planning to use zIIP processing must do either of these:
<ul>
<li>Inspect any user-written $functions for non-tolerant code. This is code that uses an explicit SVC instruction or requests system services that might use an SVC, like BSAM, VTAM, or task-mode z/OS macros, or macros that are not allowed to be invoked on an SRB (enclave Service Request Block, the environment when a $function is executed on a zIIP processor). Bracket this code with <code>SRBMODE OFF</code> and <code>SRBMODE ON</code>. </li>

<li>Specify <code>MP=NO</code> (the default) or no <var>MP</var> setting at all in the FN macro to cause $functions to run on the maintask and not on a zIIP SRB. Any other value for <var>MP</var> enables $functions to run on zIIP subtasks. </li>
</ul>
Note: It is not always obvious if code may or may not run on a zIIP subtask. Even if all explicit SVCs and non-task-mode system macros issued by Model 204 have been identified and bracketed, some may be issued implicitly by z/OS or other services, so user testing is important. 

[[Category:System management]]
[[Category:Model 204 operational issues]]

Customizing functions and translation tables

2015-07-14T18:41:13Z

Tbullock: Add longstring - (LTORG is hidden in the POOL macro)

==Overview==

User-written SOUL functions are stored in the user function module FUNU. The FUNU module is distributed as a skeletal module containing a table for functions and arguments, and the assembler code for one function. You can list the contents of FUNU using the procedures given in the Rocket Model 204 Installation Guide for your operating system.

The Encoding/Decoding facility uses the translation tables contained in the distributed CDTB module. The <var>$Code</var> and <var>$Decode</var> functions access the translation tables to allow the use of both coded and string values of fields. The contents of the translation tables can be listed by using the procedures listed in the Rocket <var class="product">Model 204</var> Installation Guide for your operating system.

You can store messages and return codes for user-written functions in the MSGU module. 

This page gives the procedures for adding user-written functions to the FUNU module, customizing the translation tables contained in the CDTB module, and adding messages to MSGU.

If you are migrating to 31-bit or multiprocessing environments, review the conversion considerations summarized in [[#Converting user-written functions|Converting user-written functions]]. 

For general directions on assembly and link-editing, see the Rocket <var class="product">Model 204</var> Installation Guide for your operating system. 

==Adding functions to the FUNU module==

You can add user-written functions to the FUNU module before FUNU is assembled and linked into <var class="product">Model 204</var>. Reassembly and relinking is required whenever you migrate to another release of <var class="product">Model 204</var>.

To add functions to the FUNU module:
<ol>
<li>Label the function table in the FUNU source code FUNUTAB. </li>

<li>End the function table in the FUNU source code with <code>DC X'FFFF'</code>.

The location of the function table in the code is not significant.
</li>

<li>Make the new function available to the <var class="product">Model 204</var> SOUL compiler by adding an entry to the function table using the FN macro:
FN function-name, R-type, (A-type [, A-type]...),ROUTINE=

Where:
<ul>
<li><var class="term">function-name</var> specifies a unique 1- to 7-character name of the function without the leading <code>$</code>. Spaces or special characters are not allowed.

User-written functions must not duplicate the name of Rocket Software functions. A list of Rocket Software functions is given in [[SOUL $functions]].</li>

<li><var class="term">R-type</var> represents the type of value returned from the function. Only one value can be returned. <code>S</code> represents a string value. <code>N</code> represents a numeric value. </li>

<li><var class="term">A-type</var> describes the type of argument value. More than one argument can be specified. <code>S</code> represents a string value. <code>N</code> represents a numeric value. </li>


In the following example, <code>$SEP</code> receives three string arguments and returns a string value:
FN SEP,S,(S,S,S)

</li>

<li><var class="term">ROUTINE=</var> identifies the name on the ENTER macro of the routine that actually implements the function. This allows the name of the $function (the name on the FN macro) to be greater than 7 characters.</li>
For example, one of the MQ/204 $functions, $MQ_FIND_QUEUE_ENTITY, has these two entries (not in FUNU) for FN and ENTER:

FN MQ_FIND_QUEUE_ENTITY,S,(S,S),MP=OK,ROUTINE=$MQFNDQ
...
$MQFNDQ ENTER ZMODE=64
assembly language code for the function
LEAVESTR

</li>
</ul>

<li>Code the function (as described in [[#Coding a function|Coding a function]].</li>
</ol>

==Coding a function==
===Coding conventions===

The following conventions are required for coding a user-written function:
<ul>
<li>Begin the function code with:
$name ENTER
</li>

<li>End the function code with:
POOL
</li>

<li>Observe the following register conventions (correspondence between Rocket Software mnemonic names and IBM general registers is printed at the beginning of the module in the expansion of the STARTS macro):
<ul>
<li>Registers RC, R6, PD, and RL must not be modified.</li>

<li>Registers T1 through T5 and R1 through R5 can be used as work registers.</li>

<li>Registers R1 through R5 are somewhat more permanent. </li>

<li>Use BUF1 and BUF2 (260 bytes each) as buffers (doubleword aligned). </li>

<li>Use string, numeric, or omitted arguments. </li>
</ul></li>
</ul>

===String arguments===

If the <var class="term">n</var>th argument is type <var>S</var>, you can move the argument into a work area by using the following code. Registers R1 through R4 are used by this sequence:
ARG n
L R2,4(X1)
CCALL RTSTRL
EX R2,FOO
STC R2,BUF1
.
.
FOO MVC BUF1(0),0(R1)
.

<ul>
<li>The <code>ARG</code> macro returns the VTBL pointer to the <var class="term">n</var>th argument in X1.</li>

<li>The <code>RTSTRL</code> routine sets <code>R2</code> to the length of the string, and it sets <code>R1</code> to address-1 of the string.</li>

<li>The length of the string is given by register <code>R2</code>.</li>

<li>The string is moved to <code>BUF1</code>, starting at location <code>BUF1 + 1</code>.</li>

<li>The string length is moved to location <code>BUF1</code>. </li>
</ul>

===Numeric arguments===

If the <var class="term">n</var>th argument of a function is type <var>N</var>, you can obtain the argument in floating-point form or binary integer form (truncated or rounded) using registers R1 through R3, as follows: 
ARG n
LA R3,x
CCALL INTEG
.
.
.


Where:
<ul>
<li><var class="term">x</var> = 0, if a truncated value is required.</li>

<li><var class="term">x</var> = <var class="term">value,</var> if a rounded value is required. </li>
</ul>

After this sequence, F0 contains the original floating-point value. If the number is valid, R1 contains the integer portion of the number as a binary value and R2 is zero. If the number is invalid, R1 is zero and R2 is nonzero.

===Omitted arguments===

When writing a call to a function, you can omit an argument, as follows:
$Read( )
$Substr(NAME,,5)


Where:
<ul>
<li>If the omitted argument is type <var>S</var>, the value of the argument defaults to a null string.</li>

<li>If the argument is type <var>N</var>, the value defaults to zero. </li>
</ul>

====NOARG option====

You can specify the <var>NOARG</var> option on the ARG macro in the event that an argument is omitted. When <var>NOARG</var> is used, the code branches to the location indicated by the <var>NOARG</var> option. For example:
ARG n,NOARG=ALLDONE
L R2,4(X1)
CCALL RTST
.
.
.
CCALL DKRL
ALLDONE DS OH
.
.
.
LEAVESTR


You can also specify the following, which returns control to the next sequential instruction after the <var>ARG</var> statement:
NOARG = *


===Using the ENTER macro to allocate working storage===

You can use the <var>VARS</var> argument of the ENTER macro to define stack variables for working storage unique to each user-written function. This method of allocating storage is preferable to STORAGE, GETMAIN, and FREEMAIN instructions. Using the ENTER macro avoids the possibility of causing Online waits or having all users share the same storage.

====Syntax for ENTER VARS====
ENTER VARS = (, X
(varname1, varlength1), comments X
(varname2, varlength2), comments X
(varname3, varlength3), comments X
.
.
.
), AMODE=n


You must initialize each of these variables.

====Routines available for user written $functions====

There are CCALL entry points for: DATE, DATE3, and DATE4. All routines must be called with T1 pointing to a 26-byte answer area. Rocket Software recommends that you allocate the answer area using the <code>VARS=(name, len)</code> pushdown list variable of the ENTER macro.
The following table lists how the current date and time is stored in the area with this format:
<table>
<caption>Formats used to store the date routines</caption>
<tr class="head">
<th>Code entry point</th>
<th>Format used for storing...</th>
</tr>

<tr>
<td>
DATE
</td>
<td>
'YY.DDD MON DD HH.MM.SS'
</td>
</tr>

<tr>
<td>
DATE3
</td>
<td>
'CYY.DDD MON DD HH.MM.SS'
</td>
</tr>

<tr>
<td>
DATE4
</td>
<td>
'YYYY.DDD MON DD HH.MM.SS'
</td>
</tr>
</table>

All registers are returned intact with the exception of the DATE call. The DATE call changes only the T4 register, returning the number representing the current month (1-12).

Note that there are double SPACEs before and after the "MON DD".

===Return values===

Functions can return a string or a numeric value. The following coding considerations apply:
<ul>
<li>To return a string value, end the function routine by doing the following:
<ol>
<li>Load R1 with a pointer to the location of the result string minus one.</li>

<li>Load R2 with the length of the result string.</li>

<li>Issue the LEAVESTR macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
</ol></li>

<li>To return a numeric value, end the function routine in one of the following ways, depending on how the result is computed:
<ul>
<li>For an integer result, end the code end with the following:
<ol>
<li>Load the binary integer into R1.</li>

<li>Zero R2.</li>

<li>Issue the LEAVENUM macro just before POOL or LTORG.</li>
</ol></li>

<li>For a floating-point result, end the code with the following:
<ol>
<li>Load F0 with the long floating-point number.</li>

<li>Issue the LEAVEF0 macro just before POOL or LTORG.</li>
</ol></li>

<li>To return a longstring value, end the function routine by doing the following:
<ol>
<li>Load R1 with a pointer to the location of the result longstring minus one. If very long it will have to be above the bar.</li>
<li>Load R2 with the length of the result longstring.</li>
<li>Issue the LEAVELST macro at the end of the code, just before POOL or LTORG to drop local addressability.</li>
</ol></li>

<li>To avoid affecting the performance of <var class="product">Model 204</var> multithreading operations, ensure that a SOUL function does not invoke any kind of synchronous operating system service that could result in a wait.</li>
</ul></li>
</ul>

===Coding messages===

You can add messages and codes specific to user-written functions by adding EDEF message lines to the MSGU module. These are referenced in your functions by invoking the ERROR macro.

To code and activate messages and return codes:
<ol>
<li>Add EDEF statements to MSGU as needed in place of the dummy EDEF in the distributed module.</li>

<li>Add ERROR macros to your functions, referring to messages in MSGU by message number as follows:
ERROR errnum,OPT=USER
</li>

<li>Reassemble MSGU and FUNU.</li>

<li>Relink the <var class="product">Model 204</var> modules (for example BATCH204, ONLINE) in which MSGU and FUNU are included.</li>
</ol>

====EDEF statements in MSGU====

Each EDEF statement defines a message. 

=====EDEF statement syntax=====
EDEF msgno, aaaa, class, batchrc, ssss, text


Where:
<ul>
<li><var class="term">msgno</var> denotes message number.</li>

<li><var class="term">aaaa</var> denotes action bits controlling output, snap generation, register pointers, and so on.</li>

<li><var class="term">class</var> (E, I, or P) specifies batch and Online return code requirements.</li>

<li><var class="term">batchrc</var> specifies batch return code.</li>

<li><var class="term">ssss</var> denotes snap bits controlling contents of snaps and dumps.</li>

<li><var class="term">text</var> contains message text, which can contain %variables passed by invocation of the ERROR macro.</li>
</ul>

For complete details on these EDEF arguments, refer to the internal documentation in the MSGU listing. 

==Encoding/Decoding facility==

The <var class="product">Model 204</var> SOUL <var>[[$Code]]</var> and <var>[[$Decode]]</var> functions provide the capacity to operate with both coded and string values of fields.


===CDTB module===

Define code tables in the CDTB module, which you must include in any load module needed to support the <var>$Code</var> and <var>$Decode</var> functions (usually with BATCH204 and ONLINE configurations). 

CDTB is an assembly language program consisting of:
<ul>
<li>Three macros used to define each table distributed in source code form</li>

<li>Comments explaining the macros</li>

<li>CSECT statement</li>

<li>Three sample tables</li>

<li>END statement </li>
</ul>

The macros contained in the CDTB module are:
<ul>
<li>CODETABL
CODETABL id, length 

Where:
<ul>
<li><var class="term">id</var> is a 1- to 8-character string, not enclosed in quotation marks, used to identify the table.</li>

<li><var class="term">length</var> is the length of the longest code found in the table. </li>
</ul>

The CODETABL macro builds a table header that consists of a pointer to the next table, the table identifier, the number of entries in the table, and the length of the longest code. Each table defined must specify one CODETABL macro.</li>

<li>CODE
CODE code, 'string'


Where:
<ul>
<li><var class="term">code</var> is the code not enclosed in quotation marks and not longer than the length specified in the previous CODETABL macro.</li>

<li><var class="term">string</var> is the string associated with the code and is enclosed in quotation marks. The string can have up to 255 characters. </li>
</ul>

The CODE macro builds one entry that consists of the code, the string length, and the string value. The CODE macro must be used individually for each entry in the table. </li>

<li>ENDTAB
ENDTAB

ENDTAB requires no operands and indicates the end of the current table. One ENDTAB macro is required for each table. ENDTAB completes the definition of the table by: 
<ul>
<li>Returning to the header created by the previous CODETABL macro</li>

<li>Updating the information about the pointer to the next table</li>

<li>Updating the number of entries in the table just defined</li>

<li>Setting up information to start the next table or to mark the end of all tables </li>
</ul></li>
</ul>

===Customizing the sample translation tables===

To modify the distributed sample translation tables (refer also to the Rocket <var class="product">Model 204</var> Installation Guide for your operating system): 
<ol>
<li>List CDTB with its sequence numbers.</li>

<li>Replace the sample tables by using an appropriate operating system utility program.</li>

<li>Assemble the program.</li>

<li>Link the object modules into the appropriate <var class="product">Model 204</var> load modules.</li>
</ol>

===Modifying translation tables===

To make additions, deletions, or changes to translation tables (refer also to the Rocket <var class="product">Model 204</var> Installation Guide for your operating system): 
<ol>
<li>Modify the source code.</li>
<li>Assemble the source code.</li>
<li>Link-edit the new CDTB module into the appropriate <var class="product">Model 204</var> load modules.
</li>
</ol>

===Sizing the CDTB module===

The size of the CDTB module depends on the tables defined. If tables are very large, CDTB might require a significant amount of storage, resulting in an adjustment to the REGION size.

Each table entry requires:
Number of bytes in the longest code + 1 (for string length) + the number of bytes in the string + 1


32 bytes per table is required overhead for header information.

==Converting user-written functions==

User-written $functions may need to be modified if you are migrating to 31-bit or multi-processing environment. While Rocket Software generally discourages customers from coding $functions that have extensive dependencies on <var class="product">Model 204</var> internal data structures and algorithms, some customers have found it necessary to do so. These conversion notes describe the changes required for the conversion of most $functions.
Note:
These sections do not provide complete descriptions of all internal data structure and algorithm changes that have been made to <var class="product">Model 204</var>; nor are they to be construed as official sanction on Rocket Software's part of the use of any specific interfaces or of the dependency on any specific data structure or algorithm. All such interfaces, data structures, and algorithms remain subject to change without notice.
<ul>
<li>[[#Additional requirements for systems using 31-bit architecture|Additional requirements for systems using 31-bit architecture]] applies to all sites that use 31-bit architecture. </li>

<li>[[#Additional requirements for MP/204 (multiprocessing)|Additional requirements for MP/204 (multiprocessing)]] applies to users of MP/204 (multiprocessing). </li>
</ul>

===Coding requirements for all operating systems===

Observe the following coding requirements for all operating systems:
<ul>
<li><var class="product">Model 204</var> runs in 64-bit mode and requires all registers to be saved and restored using the grande versions of the assembly instructions STM (Store Multiple) and LM (Load Multiple). All user-written functions must be reviewed and modified to use STMG and LMG instructions. </li>

<li>Change $functions that refer to KX or KY as follows:
<ul>
<li>Remove X,Y arguments from the KOMMS macro.</li>

<li>Code the new FSA macro with the same X,Y arguments that were present on the KOMMS macro.</li>

<li>Modify references to fields in KX or KY to use a different base register from the KOMM base register as follows:

L reg,KJFLKX
USING KX,reg
refer to KX or KY fields
DROP reg
</li>
</ul></li>

<li>From the CCALL MOVEIN routine, remove CCALL. This places the code inline. By expanding the code, efficiency is improved. The input and output are the same as before. However, you might have to add pool statements to the macro, since the offset points to a pool.</li>

<li>Some KOMM fields have been moved from KA-KD to KZ. While user-written $functions should not generally reference these fields, those that do need to address KZ as follows:
L reg, KBPKZ
USING KZ,reg
refer to KZ fields
DROP reg
</li>

<li>The CSAVE or IOSAVE macros replace the SETAMODE macro in the MACLIB.</li>

<li>The AMODE parameter of the ENTER macro is ignored. The CCALL, ENTER, and KARTN sequences no longer cause switches in addressing mode.</li>

<li>The XAMODE macros are now obsolete and have been deleted from Rocket Software-delivered MACLIBs. Consequently, it is no longer necessary to maintain XAMODE$U. </li>

<li>Reassemble FUNU and FUNUUG. </li>
</ul>

===Additional requirements for systems using 31-bit architecture===

All code receives control in 31-bit mode. See IBM z/OS/XA Principles of Operation for differences between 24-bit and 31-bit mode operation:
<ul>
<li>Nearly all <var class="product">Model 204</var> data structures (servers and PCBs, for example) are in 31-bit storage. Pointers to such data structures must be 31-bit addresses. Three-byte address constants, for example <code>AL3(xyz)</code>, cannot be used as pointers.</li>

<li>Code that explicitly manipulates <var class="product">Model 204</var> four-byte string codes must be modified to remove the high-order byte from the string code prior to adding KUPVT or KUPST. </li>

<li>If you invoke a z/OS service that must receive control in 24-bit mode (such as BSAM) use CSAVE or IOSAVE with the <code>AMODE=24</code> parameter. Code CRSTR or IORSTR with the <code>AMODE=31</code> parameter. You cannot reference KOMM or the pushdown list between <code>AMODE=24</code> and <code>AMODE=31</code> brackets.</li>

<li>The <var>NOARG</var> parameter (described in [[#NOARG option|NOARG option]]) is required for <var>ARG</var> statements in 31-bit mode.</li>

<li>You cannot use the CCALL macro in 24-bit mode. </li>

<li>For users of the multiple KOMM feature:
<ul>
<li>If the $function switches to z/OS register conventions, RC might at some point no longer be equal to KOMM. Use the following code to locate KOMM:
CURROSW REG=x
LLGF y,OSWPUK-OSW(,x)
</li>

<li>In ESA systems, each user's KOMM is allocated in 31-bit storage.

(See the discussion of MP system parameters in [[Performance monitoring and tuning]]). 
</li>
</ul></li>
</ul>

===Additional requirements for MP/204 (multiprocessing)===
<ul>
<li>The FN macro has an MP argument, which defaults to <code>NO</code>. Other legal values are <code>OK</code> and <code>YES</code>. When the FN macro specifies <code>MP=NO</code>, the $function is guaranteed to execute in the maintask.</li>

<li>When a $function is invoked that specifies <code>MP=OK</code>, that $function might execute in one of the MP subtasks, depending on whether <var class="product">Model 204</var> is running in parallel a section of code that contains it. If so, the $function is eligible to execute in a subtask.</li>

<li>When a $function is invoked that specifies <code>MP=YES</code>, that $function executes in one of the MP subtasks, regardless of whether the section of code within which it is contained is running in parallel. Usually, only $functions with relatively long pathlength should specify <code>MP=YES</code>, because the cost of switching from the maintask to a subtask can be in the thousands of instructions. Because the exact cost of switching tasks depends on how busy the subtasks and the maintask are, measurements should be made in marginal circumstances.</li>

<li>$functions that are eligible for subtask execution actually execute on one of the subtasks under either of the following conditions:
<ul>
<li><code>SCHDOPT=X'02'</code> is specified.</li>

<li>The section of code in which the $function is coded is executed at a time when other users are on the scheduler's READY queue. </li>
</ul></li>

<li>$functions that specify <code>MP=OK</code> or <code>MP=YES</code>:
<ul>
<li>Are not guaranteed to always execute in the same subtask when <var>[[NMPSUBS parameter|NMPSUBS]]</var> is greater than 1. </li>

<li>Must be re-entrant.</li>

<li>Must not use any internal <var class="product">Model 204</var> interfaces that require maintask execution, for example, APUT, DKIW, and CENQxxx.</li>
</ul></li>

<li><code>MP=OK</code> and <code>MP=YES</code> have no effect when the MP feature is not in use (<code>NMPSUBS=0</code>).</li>
</ul>

===Additional requirements for zIIP processing===
If Model 204 runs with [[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|zIIP processors]], an <code>MP=YES</code>, <code>MP=OK</code>, <code>MP=ZYES</code>, or <code>MP=ZOK</code> setting in the FN macro might cause a $function to be executed on the zIIP subtask, which does not allow an SVC instruction. Customers planning to use zIIP processing must do either of these:
<ul>
<li>Inspect any user-written $functions for non-tolerant code. This is code that uses an explicit SVC instruction or requests system services that might use an SVC, like BSAM, VTAM, or task-mode z/OS macros, or macros that are not allowed to be invoked on an SRB (enclave Service Request Block, the environment when a $function is executed on a zIIP processor). Bracket this code with <code>SRBMODE OFF</code> and <code>SRBMODE ON</code>. </li>

<li>Specify <code>MP=NO</code> (the default) or no <var>MP</var> setting at all in the FN macro to cause $functions to run on the maintask and not on a zIIP SRB. Any other value for <var>MP</var> enables $functions to run on zIIP subtasks. </li>
</ul>
Note: It is not always obvious if code may or may not run on a zIIP subtask. Even if all explicit SVCs and non-task-mode system macros issued by Model 204 have been identified and bracketed, some may be issued implicitly by z/OS or other services, so user testing is important. 

[[Category:System management]]
[[Category:Model 204 operational issues]]

Talk:$FlsAcc

2015-06-05T23:46:12Z

Tbullock: To many $$

Wiki won't let me update the initial part of this page.
There are too many $$ in $$FlsChk In two places.

$Dsn

2015-06-05T22:18:00Z

Tbullock: 44 bytes in z/OS anyway, I don't know about CMS or VSE...

$DSN is useful with <var class="product">Model 204</var> files that are comprised of multiple data sets. You specify the <var class="product">Model 204</var> file's DD name and the ordinal number (first, second, third, and so on) of one of the file's data sets, and $DSN returns the data set's name. 
The $DSN syntax is:
$DSN('ddname',dsnnum)

where:
<ul>
<li><var class="term">ddname</var> is a <var class="product">Model 204</var> file's DD or file name. The file that you specify must be OPEN by you while you are using $DSN. This ensures reliable output.</li>
</li>
<li><var class="term">dsnnum</var> is a positive integer that represents the ordinal number of a data set. For example, specify 3 for <var class="term">dsnnum</var> if you want the name of the third of the multiple data sets that comprise the <var class="product">Model 204</var> file.</li>
</li>
</ul>
If no file or DD name is specified, if the data set number is too large, and if <var class="product">Model 204</var> cannot find the data set name, the system returns a counting error message.
The output string is right-filled with SPACEs to 44 bytes.
Examples
An example using $DSN follows:
FOR %I FROM 1 TO $DSNNUM('FU') BY 1
PRINT %I AND $DSN('FU',%I)
END FOR

The next example does a straight $DSN call for a file mapped to one data set.
%FILENAME IS STRING LEN 8
%FILENAME = 'VEHICLES'
PRINT 'FILE ' WITH %FILENAME WITH ' IS CONTAINED IN -
DATASET ' WITH $DSN(%FILENAME,1)

[[Category:SOUL $functions]]

$Dsn

2015-06-04T18:24:08Z

Tbullock: $DSNNUM only takes one parameter, not two.

$DSN is useful with <var class="product">Model 204</var> files that are comprised of multiple data sets. You specify the <var class="product">Model 204</var> file's DD name and the ordinal number (first, second, third, and so on) of one of the file's data sets, and $DSN returns the data set's name. 
The $DSN syntax is:
$DSN('ddname',dsnnum)

where:
<ul>
<li><var class="term">ddname</var> is a <var class="product">Model 204</var> file's DD or file name. The file that you specify must be OPEN by you while you are using $DSN. This ensures reliable output.</li>
</li>
<li><var class="term">dsnnum</var> is a positive integer that represents the ordinal number of a data set. For example, specify 3 for <var class="term">dsnnum</var> if you want the name of the third of the multiple data sets that comprise the <var class="product">Model 204</var> file.</li>
</li>
</ul>
If no file or DD name is specified, if the data set number is too large, and if <var class="product">Model 204</var> cannot find the data set name, the system returns a counting error message.
Examples
An example using $DSN follows:
FOR %I FROM 1 TO $DSNNUM('FU') BY 1
PRINT $DSN('FU',%I)
END FOR

The next example does a straight $DSN call for a file mapped to one data set.
%FILENAME IS STRING LEN 8
%FILENAME = 'VEHICLES'
PRINT 'FILE ' WITH %FILENAME WITH ' IS CONTAINED IN -
DATASET ' WITH $DSN(%FILENAME,1)

[[Category:SOUL $functions]]

File Control Table (File architecture)

2015-03-06T19:22:02Z

Tbullock: Mention the majority 7/8ths of the FCT.

The File Control Table contains the file parameter settings, data set or file definition names of all data sets in the file, the status of the file, and other control information.

The FCT is 8 pages.

The first page of the FCT is the File Parameter List (FPL) page, which contains:
<ul>
<li>The File Parameter List holding the current parameter settings for the file </li>

<li>The Logical Page Map (LPM) which shows the distribution of the pages within the file </li>

<li>The data sets list (DSL) comprising the name and number of pages in each data set </li>

<li>The shared DASD enqueue list, which:
<ul>
<li>Controls access to the file by multiple jobs, potentially running on different processors that share the DASD device upon which the file data sets reside </li>

<li>Contains the enqueue level of each of those jobs. The <var>[[ENQCTL command|ENQCTL]]</var> command enables you to display the enqueue list. </li>
</ul> </li>

<li>The current file [[BROADCAST command: Sending a file message|broadcast]] message (if any), displayed when the file is [[OPEN FILE command|opened]]. </li>
</ul>

The remaining seven pages of the FCT are empty. They were used in very early versions of M204, but are now 'Reserved for Future Use'.

[[Category:File architecture]]

SYSDATE parameter

2015-03-05T18:09:21Z

Tbullock: Add the syntax.

{{Template:SYSDATE parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>Current operating system time
<dt>Parameter type
<dd>System
<dt>Where set
<dd>user 0 CCAIN parameter list only
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V6.1</var> or earlier
</dl>
==Description==
The SYSDATE parameter lets you set the initial system date to a given value. The SYSDATE and SYSTIME parameters must both be specified together, unless SYSDATE=+DDD is specified. The format for the parameter value is: SYSDATE=yyyy/mm/dd or SYSDATE=+ddd 
SYSDATE may not be in the past, and may not be after 2042/09/17 when the old-style 8-byte hardware Time Of Day clock value wraps to zero.
[[Category:System parameters]]
[[Category:Parameters]]

SYSTIME parameter

2015-03-05T18:00:50Z

Tbullock: Actually say what the format is...

{{Template:SYSTIME parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>Current operating system time
<dt>Parameter type
<dd>System
<dt>Where set
<dd>User 0 CCAIN parameter list only
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V6.1</var> or earlier
</dl>
==Description==
The SYSTIME parameter lets you set the initial system time to a given value. The SYSDATE and SYSTIME parameters must both be specified together, unless SYSDATE=+DDD is specified. The format for the parameter value is: SYSTIME=hh:mm:ss
[[Category:System parameters]]
[[Category:Parameters]]

Page (File architecture)

2015-03-04T01:01:01Z

Tbullock: Deleted the link; it is not that kind of initialize.

A page is the underlying structure applied to the data sets that comprise a Model 204 file.

All pages are 6184 bytes.

When a file is [[Creating a file|created]], the pages in the file are formatted into:
<ul>
<li>6144 bytes of "usable" space (how the space is used depends on the table where the page resides)
<li>A 40 byte page trailer
</ul>

==The page trailer==
The page trailer contains the following:
<ul>
<li>The file name, which is the name used in the [[CREATE command: File|create]] process.</li>

<li>The date/time when the individual page was last initialized.</li>

<li>The date/time when the page was last written to the file.</li>

<li>Data used in the [[CHECKPOINT command|checkpoint]] process.</li>

<li>The table that this page is part of, the numeric representation for which is as follows:
FCT = 00, Table A = 01, Table B = 02, Table C = 03, Table D = 04, Table E = 40, and Table X = 20.</li>

<li>The sequential page number within the table. Three byte binary integer.
Because of <var>[[INCREASE command|INCREASE]]</var> and <var>[[DECREASE command|DECREASE]]</var> commands after the initial <var>CREATE</var>, the pages for a table might not be contiguous.</li>
</ul>

[[Category:File architecture]]

RESTORE command

2015-03-03T18:44:36Z

Tbullock: Spell BRAODCAST more gooder.

==Summary==
<dl>
<dt>Privileges
<dd>File manager plus ad hoc updates
<dt>Function
<dd>Restores a <var class="product">Model 204</var> file from a dumped version of that file
</dl>

==Syntax==
RESTORE [option] FROM ddname


Where:
<table>
<tr>
<th>option</th>
<td>A decimal value. Options can be summed. The options are:
<table>

<tr class="head"> <th>Option</th>
<th>Meaning</th> </tr>

<tr> <th align="right"><var>128</var></th>
<td>The size of a file data set or the number of data sets in a file is being changed. </td> </tr>

<tr> <th align="right"><var>64</var></th>
<td>The name of a file is being changed.</td> </tr>
</table>
</td></tr>

<tr>
<th>ddname</th>
<td>The name of the data set from which the <var class="product">Model 204</var> file is being restored. If the <var>FROM</var> <var class="term">ddname</var> clause points to a data set that was not created by the <var class="product">Model 204</var> <var>DUMP</var> command, the following error messages is issued:
M204.2711: <var class="term">ddname</var> IS NOT A DUMP DATASET, CANNOT RESTORE INTO <var class="term">ddname2</var>
</td>
</tr>

</table>

==Example==
OPEN CEN
M204.0620: FILE CEN OPENED
M204.1203: FILE CEN WAS LAST UPDATED ON hh:mm:ss
RESTORE 192 FROM DUMPCEN 
M204.0500: FILE CEN: RESTORING FROM DUMP OF 88.262 SEP 19 14.24.29
M204.1760: FILE CEN: RESTORE BEGINNING AT 14.29.06
M204.1761: FILE CEN: RESTORE COMPLETED AT 14.29.24


==Usage notes==
<ul>
<li>The <var>RESTORE</var> command restores a <var class="product">Model 204</var> file from a dumped version of that file. <var>RESTORE</var> takes a sequential data set produced by a <var>[[DUMP command|DUMP]]</var> command and turns it into a <var class="product">Model 204</var> file again.
Note: Before using the <var>RESTORE</var> (or <var>[[REGENERATE command|REGENERATE]]</var>) command, you need to have <var>DUMP</var> copies of the files. <var>DUMP</var> processing updates the file while making a backup copy (to a target media). Otherwise, when you do a media recovery using either <var>RESTORE</var> (which does not include journals) or <var>REGENERATE</var> (to include journals), the backup copy does not incorporate all updates, and you cannot detect this.</li>

<li>The <var>RESTORE</var> command can be issued only in file context. (That is, the current default must be a file, not a group.) The file must be opened with file manager privileges and privileges to update with ad hoc requests.</li>

<li>If an external security interface is active, the user ID issuing the command is checked for the proper data set usage authorization. If the authorization check fails, the attempt is logged as a security violation and the command is not executed. Under a security interface, you must have READ privileges to read a file specified by this command. For more information, refer to the [[:Category:Security interfaces|Security interfaces]] pages.</li>

<li>If a file is skewed, the file can only be transferred from one device type to another through the <var class="product">Model 204</var> DUMP/RESTORE facility. File skewing is an obsolete feature.</li>

<li>When <var>RESTORE</var> has finished processing, it automatically closes all private or semi-public files. Public files remain open.</li>

<li>When it processes <var>RESTORE</var>, <var class="product">Model 204</var> ends any [[File integrity and recovery#Update units and transactions|update unit]] in progress and begins a non-backoutable update unit. </li>

<li>After <var class="product">Model 204</var> starts to restore a file, it displays a message showing the date and time the file was dumped. [[File dumping and restoring]] discusses the <var>RESTORE</var> options, along with a full presentation of <var>DUMP</var>, <var>RESTORE</var>, and their use in moving, renaming, and changing the size of files.</li>

<li>Although the <var>DUMP</var> command copies the <code>FILE BROADCAST</code> message with the FPL, the <var>RESTORE</var> command leaves the current <var>[[BROADCAST command|BROADCAST]]</var> message in the file. For example:</li>
OPEN FPLJUNK
BROADCAST FILE BROADCAST MESSAGE NUMBER ONE
DUMP TO DUMPFPL
OPEN FPLJUNK
BROADCAST FILE BROADCAST MESSAGE NUMBER TWO
RESTORE FROM DUMPFPL
OPEN FPLJUNK
<broadcast message number two> is displayed.
</li>
</ul>

[[Category: File manager commands]]
[[Category:Commands]]

LITBL parameter

2015-02-19T23:45:44Z

Tbullock: Clean up and add class="code" to messages

{{Template:LITBL parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>0
<dt>Parameter type
<dd>Utable
<dt>Where set
<dd>On user's parameter line or reset by <var>[[UTABLE_command|UTABLE]]</var> command
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V2.2</var> or earlier
</dl>

==Description==
<var>LITBL</var> specifies the size of ITBL in bytes.
<var>LITBL</var> is used to store dummy string and <var>[[$Read]]</var> responses entered on <var>[[INCLUDE command|INCLUDE]]</var> lines.
<var>LITBL</var> can range from 0 to 32760 and will be rounded up to a multiple of 8.
Verification messages may be issued:
M204.0102: LITBL reset clears stacked arguments M204.1076: Do you really want to CONTINUE

[[Category:Utable parameters]]
[[Category:Parameters]]

LGTBL parameter

2015-02-19T23:32:38Z

Tbullock: Rounds up to 8.

{{Template:LGTBL parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>288
<dt>Parameter type
<dd>Utable
<dt>Where set
<dd>On user's parameter line or reset by <var>[[UTABLE command|UTABLE]]</var> command
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V2.1</var> or earlier
</dl>

==Description==
The size of GTBL in bytes.
GTBL contains global variables. The value of LGTBL can range from 40, the minimum, to 2 billion. It will be rounded up to a multiple of 8. For an application subsystem user, (LGTBL - (<var>[[GTBLHASH parameter|GTBLHASH]]</var>*10) must not be less than 288.
Refer to [[UTABLE command]] for a discussion of changing the size of LGTBL.

[[Category:Utable parameters]]
[[Category:Parameters]]

LITBL parameter

2015-02-19T00:48:00Z

Tbullock: Add rounding to 8. Add the message you will sometimes get when changing from 0 to a larger number. (But why does that only seem to happen when increasing and not decreasing?)

{{Template:LITBL parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>0
<dt>Parameter type
<dd>Utable
<dt>Where set
<dd>On user's parameter line or reset by <var>[[UTABLE_command|UTABLE]]</var> command
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V2.2</var> or earlier
</dl>

==Description==
<var>LITBL</var> specifies the size of ITBL in bytes.
<var>LITBL</var> is used to store dummy string and <var>[[$Read]]</var> responses entered on <var>[[INCLUDE command|INCLUDE]]</var> lines. <var>LITBL</var> can range from 0 to 32760.
<var>LITBL</var> will be rounded up to a multiple of 8 bytes.
Messages:
M204.0102: LITBL reset clears stacked arguments 
M204.1076: Do you really want to CONTINUE 
may be issued.

[[Category:Utable parameters]]
[[Category:Parameters]]