File control command options

Some of the file control command options you may specify are:

Use of the LENGTH option varies, depending on how you use the other options.

The RIDFLD option

Whatever you do to a record (read, add, delete, or start a browse), you identify the record by the RIDFLD option, except when you have read the record for update first. However, there is no RIDFLD for ENDBR, REWRITE, and UNLOCK commands. Further, during a browse using READNEXT or READPREV commands, you must include the RIDFLD option to give CICS® a way to return the identifier of each record retrieved.

The RIDFLD option identifies a field containing the record identification appropriate to the access method and the type of file being accessed.

The RIDFLD option by itself is not always enough to identify a specific record in the file. So, when retrieving records from a KSDS, or from a KSDS or ESDS by way of an alternate index path, or when setting a starting position for a browse in this type of data set, you can have one or both of the further options GTEQ and GENERIC with your command.

With READNEXT or READPREV commands, the application program would not usually set the RIDFLD field. After each command, CICS updates this field with the actual identifier of the record retrieved. (You can alter the RIDFLD value to set a new position from which to continue the browse.)

The INTO and SET options

With the READ, READNEXT or READPREV commands, the record is retrieved and put in main storage according to your INTO and SET options.

The INTO option specifies the main storage area into which the record is to be put.

For fixed-length records, you need not include the LENGTH option. If you do, the length specified must exactly match the defined length; otherwise, you get the LENGERR condition.

For variable-length records, always specify (in the LENGTH option) the longest record your application program accepts (which must correspond to the value defined as the maximum record size when the data set was created); otherwise, you get the LENGERR condition. LENGERR occurs if the record exceeds the length specified, and the record is then truncated to that length. After the record retrieval, if you include the LENGTH option, the data area specified in it is set to the actual record length (before any truncation occurs).

The SET option specifies a pointer to the buffer in main storage acquired by CICS to hold the record. When using the SET option, you need not include the LENGTH option. If you do include it, the data area specified is set to the actual record length after the record has been retrieved.

The FROM option

When you add records (using the EXEC CICS WRITE command), or update records (using the REWRITE command), specify the record to be written with the FROM option.

The FROM option specifies the main storage area that contains the record to be written. In general, this area is part of the storage owned by your application program. With the REWRITE command, the FROM area is usually (but not necessarily) the same as the corresponding INTO area on the READ UPDATE command. The length of the record can be changed when rewriting to a KSDS with variable-length records.

Always include the LENGTH option when writing to a file with variable-length records. If the value specified exceeds the maximum allowed in the cluster definition, LENGERR is raised when the command is executed. LENGERR is also raised if the LENGTH option is omitted when accessing a file with variable-length records.

When writing to a file with fixed-length records, CICS uses the length specified in the cluster definition as the length of the record to be written, so you need not have the LENGTH option. If you do, its value is checked against the defined value and you get a LENGERR condition if the values do not match.

The TOKEN option

The TOKEN option is a unique value within a task that is supplied by CICS on any valid read for update command, and you return this to CICS with an associated REWRITE, DELETE, or UNLOCK command. For each file that is being updated by a task, at any one time you can have only one outstanding read request with the UPDATE option that does not specify the TOKEN option.

You can perform multiple concurrent updates on the same data set using the same task by including the TOKEN option with a read for update command, and specifying the token on the associated REWRITE, DELETE, or the UNLOCK command. Note that, for files accessed in non-RLS mode, a set of concurrent updates fails if more than one record is being updated in the same CI, irrespective of the TOKEN associated with the request. Also, only one token remains valid for a given REQID on a browse, and that is the one returned on the last READNEXT or READPREV command (see Updating and deleting records in a browse (VSAM RLS only)).

You can function ship a read for update request containing the TOKEN option. However, if you function ship a request specifying TOKEN to a member of the CICS family of products that does not recognize this keyword, the request fails.

KEYLENGTH option for remote data sets

In general, file control commands need the RIDFLD and KEYLENGTH options. The KEYLENGTH option can be specified explicitly in the command, or determined implicitly from the file definition.

For remote files for which the SYSID option has been specified, the KEYLENGTH option must be specified if the RIDFLD option is passing a key to file control. If the remote file is being browsed, the KEYLENGTH option is not required for the READNEXT or READPREV command.

For a remote BDAM file, where the DEBKEY or DEBREC options have been specified, KEYLENGTH (when specified explicitly) should be the total length of the key (that is, all specified subfields).

[[ Contents Previous Page | Next Page Index ]]