DosEditName (FAPI)

This call edits file and subdirectory names indirectly by transforming one ASCII string into another, using global file name characters for editing or search operations on the string.

Syntax

DosEditName (EditLevel, SourceString, EditString, TargetBuf, TargetBufLen)

Parameters

EditLevel (USHORT) - input

The level of editing semantics to use in transforming the source string. The value of EditLevel must be 0001H for OS/2 Version 1.2.

SourceString (PSZ) - input

Address of the ASCIIZ string to transform. Global file name characters are specified only in the subdirectory or file name component of the path name and are interpreted as search characters.

EditString (PSZ) - input

Address of the ASCIIZ string to use for editing. Global file name characters specified in the edit string are interpreted as editing characters. Because only the name component of a path name is transformed, this string does not include the path component.

TargetBuf (PBYTE) - output

Address of the buffer to store the resulting ASCIIZ string in.

TargetBufLen (USHORT) - input

The length of the buffer to store the resulting string in.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER
• 123 ERROR_INVALID_NAME

Remarks

DosEditName is used to search for and edit names of files and subdirectories. This call is typically used in conjunction with calls like DosMove and DosCopy, which do not permit the use of global file name characters, to perform repetitive operations on files.

As an example of an editing operation, a SourceString of "foo.bar" specified with an EditString of "*.baz" results in "FOO.BAZ" being returned. In the editing process, the string is changed to uppercase.

Global file name characters have two sets of semantics; one for searching and one for editing. If they are specified in SourceString, they are interpreted as search characters. If they are specified in EditString, they are interpreted as editing characters.

Use of the OS/2 COPY utility illustrates this difference in semantics. For example, if a user enters:

copy *.old *.new

In the source, the "*" acts as a search character and determines which files to return to the user. In the target, the "*" functions as an editing character by constructing new names for the matched files.

When used as search characters in SourceString, global file name characters simply match files and behave like any other search characters. They have the following meanings:

• The "." has no special meaning itself but "?" gives it one.
• The "*" matches 0 or more characters, any character, including a blank. The matching operation does not cross the null character or the backslash (\), which means only the file name is matched, not an entire path.
• The "?" matches 1 character, unless what it would match is a "." or the terminating null characters, in which case it matches 0 characters. It also doesn't cross "\".

Any character other than * and ? matches itself, including ".".

Searching is case-insensitive.

Any file name that does not have a period (.) in it gets an implicit one automatically appended to the end during searching operations. For example, searching for "foo." would return "foo".

When used as editing characters in EditString, global file name characters have the following meanings:

• The "." has a special meaning for editing. The "." in the target synchronizes pointers. It causes the source pointer to match a corresponding pointer to the "." in the target. Counting starts from the left of the pointers.
• The "?" copies one character, unless what it would copy is a ".", in which case it copies 0. It also copies 0 characters when the end of the source string is reached.
• The "*" copies characters from the source to the target until it finds a source character that matches the character following it in the target.

Editing is case-insensitive and case-preserving. If conflicts arise between the case of the source and editing string, the case of the editing string is used. For example:

 source string:      "file.txt"
 editing string:     "*E.TMP"
 destination string: "filE.TMP" 
 
 copy file.txt  *E.tmp  ->  filE.tmp

Bindings

C

#define INCL_DOSFILEMGR

USHORT  rc = DosEditName(EditLevel, SourceString, EditString, TargetBuf,
                          TargetBufLen);

USHORT  EditLevel;     /* Level of meta editing semantics  */
PSZ     SourceString;  /* String to transform  */
PSZ     EditString;    /* Editing string */
PBYTE   TargetBuf;     /* Destination string buffer  */
USHORT  TargetBufLen;  /* Destination string buffer length */

USHORT  rc;            /* return code */h

MASM

EXTRN DosEditName:FAR
INCL_DOSFILEMGR     EQU 1

PUSH   WORD   EditLevel      ;Level of meta editing semantics
PUSH@  ASCIIZ SourceString   ;String to transform
PUSH@  ASCIIZ EditString     ;Editing string
PUSH@  OTHER  TargetBuf      ;Destination string buffer (returned)
PUSH   WORD   TargetBufLen   ;Destination string buffer length
CALL   DosEditName

Returns WORD