DosEditName
Edits file and directory names indirectly by transforming one ASCII string into another, using global file-name characters for editing or search operations on the string.
Syntax
DosEditName(metalevel, pszSource, pszEdit, pszTarget, cbTarget)
Parameters
- metalevel (ULONG) - input
- The level of editing semantics to use in transforming the source string.
- If the value of metalevel is 1, the system uses editing semantics for OS/2 Version 1.2. Values greater than 1 are not feasible.
- pszSource (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. pszSource should contain only the component of the path name to edit, not the entire path.
- pszEdit (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.
- pszTarget (PBYTE) - output
- Address of the buffer for the resulting ASCIIZ string.
- cbTarget (ULONG) - input
- The length of the buffer, in bytes, for the resulting string.
Return Code
- ulrc (APIRET) - returns
- DosEditName returns one of the following values:
- 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. Typically, it is used in conjunction with such functions as DosMove and DosCopy, which do not permit the use of global file-name characters, to perform repetitive operations on files.
An example of an editing operation is: pszSource = "foo.bar"; pszEdit = "*.baz"; result = "FOO.BAZ." In the editing process, the string is changed to uppercase.
Global file-name characters have two uses: searching and editing. If they are specified in pszSource, they are interpreted as search characters; in pszEdit, they are interpreted as editing characters. This difference can be illustrated with an example using the COPY utility. The user types the following:
copy *.old *.new
In the source, "*" acts as a search character and determines which files to return to the user. In the target, "*" functions as an editing character by constructing new names for the matched files.
When used as search characters in pszSource, global file-name characters simply match files and behave like any other search characters. They have the following meanings:
- "." The period (.) has no special meaning itself, but "?" gives it one.
- "*" The asterisk will form a match with any character, including a blank, or with the absence of a character. The matching operation does not cross the null character or the backslash (\), which means that only the file name is matched, not an entire path.
- "?" The question mark matches 1 character, unless what it would match is a "." or the terminating null characters, in which case it matches 0 characters. It also does not cross "\".
Any character other than * and ? matches itself, including ".".
Searching is not case-sensitive.
If a file name does not have a period (.), an implicit one is automatically appended to the end during searching operations. For example, searching for "foo." would return "foo".
When used in pszEdit, global file-name characters have the following meanings:
- "." The period (.) in the target synchronizes pointers. It causes the source pointer to match a corresponding pointer to the period in the target. Counting starts from the left of the pointers.
- "?" The question mark copies one character, unless what it would copy is a period (.), in which case it copies no characters. It also copies no characters when the end of the source string is reached.
- "*" The asterisk 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 that of the 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
Example Code
This example edits the name of the file "CONFIG.SYS", using "*.CPY", and transforms it to "CONFIG.CPY". Then, it copies the contents of the original file to "CONFIG.CPY" using the DosCopy function.
#define INCL_DOSFILEMGR /* File Manager values */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
int main(VOID) {
UCHAR achSourceString[80] = "config.sys"; /* String to transform */
UCHAR achEditString[80] = "*.cpy"; /* Editing string */
UCHAR achTargetString[200] = ""; /* Destination string buffer */
APIRET rc = NO_ERROR; /* Return code */
rc = DosSetDefaultDisk(3); /* Set drive to C: (1=A, 2=B, 3=C, ...) */
if (rc != NO_ERROR) {
printf("DosSetDefaultDisk error: return code = %u\n", rc);
return 1;
}
rc = DosSetCurrentDir ("\\"); /* Set directory to root */
if (rc != NO_ERROR) {
printf("DosSetCurrentDir error: return code = %u\n", rc);
return 1;
}
/* Transform "CONFIG.SYS" using "*.CPY" to "CONFIG.CPY" */
rc = DosEditName(1, achSourceString, achEditString, achTargetString, 200);
if (rc != NO_ERROR) {
printf("DosEditName error: return code = %u\n", rc);
return 1;
}
/* Copy contents of CONFIG.SYS to the backup file */
rc = DosCopy(achSourceString, /* Name of file to be copied */
achTargetString, /* Name of the target file */
DCPY_EXISTING); /* Copy even if target file already exists */
if (rc != NO_ERROR) {
printf("DosCopy error: return code = %u\n", rc);
return 1;
} else printf ("Backup file %s created.\n", achTargetString);
return NO_ERROR;
}
