IFNFLD (HLI function)

From m204wiki
Revision as of 23:07, 12 July 2016 by ELowell (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Summary

Description
The IFNFLD call (RENAME FIELD) renames a field that has been defined as VISIBLE for a Model 204 file.

IFNFLD requires Model 204 file manager privileges.

Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
63

Syntax

IFNFLD(RETCODE,FIELD_NAMES,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_NAMES [I,c,r] This is a required input parameter that specifies the name of an existing field and its new name. Specify the names as a character string using the following format:

oldname,newname;

where:

oldname is required and specifies the existing name that is defined for the field.

newname is required and specifies the replacement name for the field. The name must be unique within the context of the file where it will be stored.

Specify the name as a character string, up to 255 characters in length. The name must begin with a letter and it can contain any alphanumeric character except the following:

  • At sign (@)
  • Pound sign (#)
  • Semi-colon (;)
  • Double question marks (??)
  • Question mark followed by a dollar sign (?$)
  • Question mark followed by an ampersand (?&)

For a detailed list of rules that apply to field names, see Field names.

FILE_SPEC [I,s,o] The file specification is an optional input parameter; it is for use only with a multiple cursor IFSTRT thread for specifying the name of the Model 204 file containing the field to be renamed. Specify the name of the file as a short character string variable using the following format:

IN [FILE] filename

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

Usage notes

Use the IFNFLD call to rename a field in a Model 204 file, only for a field that is defined as VISIBLE. The IFNFLD call is valid only in file context, not for a group. The IFNFLD call is valid on all types of IFSTRT threads.

When FOPT=X'10' and the date/time stamp feature is installed, the IFNFLD function is supported for DTS files.

Note: The file context can change on a multiple cursor thread and, if the file specification parameter (FILE_SPEC) is omitted, IFNFLD renames the field for the default file on the thread.

If the field being renamed has a security level, the Model 204 file manager must have field level security (FLS) access privileges.

Completion return code (RETCODE)

The IFNFLD call is not successful under either of the following conditions:

  • The old field name that is specified does not exist.
  • The new field name that is specified cannot be added to the Model 204 dictionary for either of the following reasons:
    • The new name that is specified already exists.
    • Space cannot be allocated.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 NAMES PIC X(20) VALUE 'SALARY,COMPENSATION;'. . . . PROCEDURE DIVISION. . . . CALL "IFNFLD" USING RETCODE, NAMES.