aftp_dir_read

The aftp_dir_read call gets an individual directory entry based on the search parameters specified in the aftp_dir_open call. A connection to the AFTP server must be established before using this call. The aftp_dir_open call must be issued before listing the directory entries.

AFTP_ENTRY aftp_dir_read(
IN AFTP_HANDLE_TYPE connection_id,
IN unsigned char AFTP_PTR dir_entry,
IN AFTP_LENGTH_TYPE dir_entry_size,
OUT AFTP_LENGTH_TYPE AFTP_PTR returned_length,
OUT AFTP_BOOLEAN_TYPE AFTP_PTR no_more_entries,
OUT AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

connection_id

An AFTP connection object originally created with aftp_create.

dir_entry

Pointer to a buffer into which the procedure will write the directory entry.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

dir_entry_size

The size in bytes of the dir_entry buffer.

returned_length

The number of bytes returned in the dir_entry buffer.

no_more_entries

Whether or not an entry was returned on this call.

A value of zero indicates that there are more directory entries and that an entry was returned on this call.

A nonzero value indicates that there are no more directory entries and no entry was returned on this call. The returned_length parameter is set to zero. Subsequent calls to aftp_dir_read will also result in no_more_entries being nonzero. To end the directory listing, your next call should be aftp_dir_close.

return_code

The return code issued for this function. See AFTP Return Codes for the list of possible return codes.

Example

This example shows how to use the aftp_dir_open, aftp_dir_read, and aftp_dir_close calls together.

{
    AFTP_HANDLE_TYPE              connection_id;
    AFTP_RETURN_CODE_TYPE         aftp_rc;
    unsigned char                 dir_entry[AFTP_FILE_NAME_SIZE +1];
    AFTP_LENGTH_TYPE              dir_entry_length;

    /* The value used for filespec will vary based on platform:
     *   VM common naming:       filespec="/a/foo*"
     *   VM native naming:       filespec="foo*.*.a"
     *   MVS PDS common naming:  filespec="/user.clist/foo*"
     *   MVS PDS native naming:  filespec="'user.clist(foo*)'"
     *   MVS sequential common:  filespec="/user.qual*.a*.**"
     *   MVS sequential native:  filespec="'user.qual*.a*.**'"
     */
    static unsigned char AFTP_PTR filespec = "/user.clist/foo*";

    unsigned char                 path[AFTP_FILE_NAME_SIZE+1];
    AFTP_LENGTH_TYPE              path_length;
    AFTP_BOOLEAN_TYPE             no_more_entries;

    /*
     * Before issuing the example call, you must have:
     *    a connection_id, use:         aftp_create()
     *    a connection to server, use:  aftp_connect()
     */

    /*
     * Open a new directory listing on the AFTP server. Both files and
     * directory names will be listed along with their attributes.
     */

    aftp_dir_open(
        connection_id,
        filespec,
        (AFTP_LENGTH_TYPE)strlen(filespec),
        AFTP_DIRECTORY | AFTP_FILE,
        AFTP_NATIVE_ATTRIBUTES,
        path,
        (AFTP_LENGTH_TYPE)sizeof(path)-1,
        &path_length,
        &aftp_rc);

    if (aftp_rc == AFTP_RC_OK) {
        path[path_length] = '\0';

        printf("Directory listing of %s.", path);

        do {
            /*
             * Read one directory entry from the AFTP server
             */

            aftp_dir_read(
                connection_id,
                dir_entry,
                (AFTP_LENGTH_TYPE)sizeof(dir_entry)-1,
                &dir_entry_length,
                &no_more_entries,
                &aftp_rc);

            if (aftp_rc == AFTP_RC_OK && no_more_entries == 0) {
                dir_entry[dir_entry_length] = '\0';
                printf("File: %s\n", dir_entry);
            }
            /*
             * Loop until we either run out of directory
             * entries or an error occurs.
             */

        } while (aftp_rc == AFTP_RC_OK && no_more_entries == 0);

        /*
         * Terminate the directory listing by executing
         * a close.
         */

        aftp_dir_close(connection_id, &aftp_rc);
        if (aftp_rc != AFTP_RC_OK) {
            fprintf(
                stderr,
                "Error closing AFTP directory.\n");
        }
    }
    else {
        fprintf(stderr, "Error opening AFTP directory.\n");
    }
}
 

Line Flows

None.