# ctaFindFileEx

Finds a file on a server using the specified default extension and environment variable.

#### Prototype

DWORD ctaFindFileEx ( CTAHD ctahd, char *filename, char *extension, char *envvar, char *fullname, unsigned size)

Argument | Description
ctahd | Context handle that specifies the server on which commands are executed. ctahd can be a void context handle.
filename | Pointer to the full or partial file name of the file to find. If a path is specified, only that path is searched. If an extension is not specified in filename, extension is appended.
extension | Pointer to the 3-letter extension to append to filename if one was not specified. If an extension is not needed, set this to NULL.
envvar | Pointer to the name of the environment variable. If filename does not include a path, the path specified by envvar is searched. If no environment variable is to be searched, set this to NULL.
fullname | Pointer to a buffer to receive the complete file name that includes the full path.
size | Size of the fullname buffer.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | filename pointer is NULL.
CTAERR_BAD_SIZE | size is too small to contain the found path.
CTAERR_FILE_NOT_FOUND | The specified file does not exist.
CTAERR_INVALID_CTAHD | Context handle is invalid.
CTAERR_NOT_INITIALIZED | Natural Access is not initialized. Call ctaInitialize first.
CTAERR_SVR_COMM | Server communications error.

#### Details

ctaFindFileEx finds the specified file. It does not open it or create it.

ctahd can be a void context handle. A void context handle refers only to the server on which the commands are executed and not to any real context object. Each server has a unique void context handle. If the void context handle is equal to NULL_CTAHD, it refers to the default server.

If filename ends with a period (.), extension is not appended to the file name.

If the file is... | Then the buffer receives the...
--- | ---
Found | Full path name of the file.
Not found | File name as provided and the optional default extension. This value can be used directly as the complete file name for opening or creating a file.

If a partial file name is specified, the server specified by ctahd determines the default directory path.

If the server is... | Then the default directory path is the path of...
--- | ---
In-process | The parent process of the application.
Local | The local server on which Natural Access Server (ctdaemon) started.
Remote | The remote server on which Natural Access Server (ctdaemon) started.

fullname includes the default extension if it is appended.

size should be at least CTA_MAXPATH long to accommodate a long directory path. If fullname is NULL, file existence is checked.

#### Example

void DemoTestFindFile()
{
DWORD ret;
char name[CTA_MAX_PATH] ;
char ext[50];
char env[50];
char fullpath[CTA_MAX_PATH] ;
CTAHD void_ctahd;
/* Server name descriptor */
char server_desc[] = "host.nmss.com:2244";
/* Create a void context handle */
ctaCreateContext(NULL_CTAQUEUEHD, 0, server_desc, &void_ctahd);
printf( "Enter file name: " );
gets( name );
printf( "Enter extension (optional): " );
gets( ext );
printf( "Enter search path environment variable: " );
gets( env );
ret = ctaFindFileEx( void_ctahd, name, ext, env, fullpath,
sizeof(fullpath) );
if (ret == SUCCESS)
printf("File found: %s\n", fullpath);
else
printf("File not found.");
}