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.");
}