HPlogo Using KSAM XL and KSAM 64 > Chapter 9 KSAM Intrinsics

FRENAME

MPE documents

Complete PDF
Table of Contents
Index

E0300 Edition 4 ♥
E0394 Edition 3

Syntax Parameters Operation Notes Condition Codes

Renames an open disk file (and its lockword, if applicable). The file being renamed must be either:

  • A new file.

  • An old file (permanent or temporary), opened for exclusive access with the exclusive option of the HPFOPEN/FOPEN intrinsics, and with security provisions allowing write access.

Syntax


           I16V     CA
  FRENAME (filenum, formaldesig);

Parameters

filenum

16-bit signed integer by value (required)

Passes the file number of the file to be renamed.

formaldesig

character array (required)

Passes the new name of the file. The maximum number of characters allowed in the string is 36. The ASCII string contained in formaldesig must begin with a letter and can contain up to eight alphanumeric characters for each of the filename, lockword, group, and account fields. The string must end with a nonalphanumeric character, including a blank, but not a slash (/) or a period (.). The home volume set of formaldesig must be the same as the file being renamed. Volume sets cannot be spanned when renaming files. The format of formaldesig is: 


  filename/lockword.group.account
where:

filename

Is the new file name for the file. (Required in formaldesig.)

lockword

Is a lockword for the new file name. (Optional portion of formaldesig.) To keep or add a lockword to the file, the lockword must be entered in the ASCII string. If this part of formaldesig is not specified, the new file name has no lockword associated with it.

group

Is the group where the file is to reside. (Optional portion of formaldesig.) If a group is not specified, the file resides in the group it was assigned before the FRENAME intrinsic call.

account

Is the account name where the file is to reside. (Optional portion of formaldesig.) If renaming a new or temporary file that was created, specify any account that shares the same volume set as the file being renamed. A permanent file cannot be renamed across account boundaries. If other than the current account name is specified for a permanent file, the CCL (1) error condition is returned and the file retains its old name.

Operation Notes

The formaldesig parameter uses MPE-escaped semantics. If a file is referenced by filenum, you can rename it within the hierarchical directory as long as the process invoking FRENAME has sufficient access and the restrictions are satified. FRENAME intrinsic fully qualifies the file owner name. Only file owners and users with appropriate privilege can manipulate a file's lockword.

If renaming a file, a process must have the following:
TD

Traverse directory entry to access to all directories specified in formaldesig. If formaldesig is specified as file.group.account, the directories are the root directory, the account, and the MPE group.

CD

Create directory entry to access to the new parent directory.

DD

Delete directory entry to access to the old parent directory.

SF

Save files capability.

The following restrictions apply to FRENAME:

  • Directories cannot be renamed.

  • Lockwords cannot be assigned to hierarchical directories.

  • Files cannot be renamed across volume sets.

  • Files with KSAM/3000, RIO, and CIR file types may only be assigned names in the MPE name space.

If a file without an ACD is renamed from an MPE group to a directory (although not within the same account), an ACD is automatically assigned to the file.

All errors will set the condition codes to CCL.

CM KSAM files cannot be renamed, but KSAM XL/64 files can be.

Condition Codes

CCE (2)

Request granted.

CCG (0)

Not returned.

CCL (1)

Request denied. An error occurred.

Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.



FREMOVE

FSPACE