IFINIT (HLI function)

From m204wiki
Revision as of 22:11, 11 July 2016 by ELowell (talk | contribs)
Jump to navigation Jump to search

The conventions used on this page are described in Function call notation conventions.

Summary

Description
The IFINIT call (INITIALIZE) initializes a Model 204 file. IFINIT deletes all records in the file and reformats all corresponding Model 204 file tables.
Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
23

Syntax

IFINIT(RETCODE,FIELD_DESC,FILE_SPEC)

Compile-only form
Not available
Execute-only form
Not available

Specify the parameters in the syntax order shown above.

Parameter Description
RETCODE [O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.
FIELD_DESC [I,c,r] The field description is a required input parameter that names a field (or fields) and lists the field attributes. You can specify a sort or hash key field description, or a record security field description, or both, for the file that is being initialized. Specify a character string using the following format:

[{SORT | HASH} RECSCTY] field description;

where:

SORT is the keyword that specifies that a sorted file is being initialized. A sorted file cannot be a hash key file (SORT and HASH are mutually exclusive).

HASH is the keyword that specifies that a hash key file is being initialized. A hash key file cannot be a sorted file (SORT and HASH are mutually exclusive).

RECSCTY is the keyword that specifies that a file having record security in effect is being initialized. A sorted or hash key file can also be initialized with record security.

field description is the name of the field, followed by a list of field attributes enclosed in parentheses. Use commas or blanks to separate attributes. Model 204 automatically supplies the following field attributes:

  • Sort field: NON-CODED, VISIBLE, STRING
  • Hash key field: NON-CODED, VISIBLE, STRING, NON-KEY
  • Record security field: KEY

You cannot specify the UPDATE option for sort or hash key field attributes. For sort or hash key fields, if a key is required in every record, specify OCCURS 1 LENGTH m. Otherwise, if keys are not required in each record, you cannot specify the OCCURS attribute.

For a record security field that is defined with the LENGTH m option, specify the value of m to be larger than the length allowed for LOGIN accounts.

Note: If no attributes are specified, Model 204 defines the field assigning all of the default attributes for the file that is being initialized. For a description of field attributes for the DEFINE command in SOUL, see Field design.

[...] indicates that a second field description can be optionally specified. If you specify both a sort or hash key field description and a record security field description, enter the record security description second. Separate each description with a comma (,). End the field description with a semicolon (;).

Note: The field description parameter is required; specify a semicolon (;) for no field description.

FILE_SPEC [I,s,o] The file specification is an optional input parameter for use only with a multiple cursor IFSTRT thread for specifying the name of the Model 204 file that is to be initialized. Specify the Model 204 file name as a short character string.

IN [FILE] filename

The specified file must be open on the thread, otherwise the call is unsuccessful and Model 204 returns a completion code of 4.

Usage notes

Use the IFINIT call to clear a file and prepare it for use. Note that IFINIT cannot be used in a group context.

The IFINIT call is permitted on all types of IFSTRT threads. On a single cursor IFSTRT thread, IFINIT always initializes the current file (that is, the last file opened). On a multiple cursor IFSTRT thread, the file context can change. And if you do not specify a particular file using the FILE_SPEC parameter, IFINIT initializes the default file (that is, the last file opened).

The IFINIT call is the equivalent of the Model 204 INITIALIZE command in the host language environment and follows the same basic rules for use. For information about using the INITIALIZE command, see Initializing files.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 INITVALS PIC X(28) VALUE 'SORT ITEMNO, RECSCTY RECSEC;'. . . . PROCEDURE DIVISION. . . . CALL "IFINIT" USING RETCODE, INITVALS.