TMCreateFile Overview Group

The TMCreateFile API function provides the information necessary (file name and extension) to create a new file and file name in the current directory on the current device on the 1-Wire network. It returns a file_handle, which can then be used later to write a file and file name to the part with a call to TMWriteFile. The new file name is provided in the FileEntry structure 'fentry'. Only the 'name' and 'extension' portions of FileEntry need to be set before calling TMCreateFile. Repeat file names are not permitted. This API returns a file handle >= 0. Please be aware that there is a limited number of file handles (4) that can be used at one time. When finished writing a file, please close the file (and free up the file handle) withTMCloseFile.

The API call also returns the estimated maximum number of bytes, ‘maxwrite,’ available for this new file. The ‘maxwrite’ variable has no meaning until returned by the funtion call (it is an output variable). The file name must be left justified padded with spaces. The valid file name characters are (ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&'-@^_`{}~). The valid value of the extension is 0-99 decimal for normal files, 100 for an ‘AddFile’ and 101 for a ‘Monetary File’. The ‘AddFile’ is described in the API function description of TMWriteAddFile. The ‘Monetary File’ is a file that is only created on a DS1962, DS1963, DS2422 and DS2423. The data page of this file can only be located on a page that has a corresponding counter. If a page with a counter is not available on the device, then the ‘Monetary File’ will not be created. In case of the ‘Monetary File’, some of its other values are set upon returning from this function. In particular, the page number where the file is copied to is set in the ‘start page’ value of the FileEntry structure. Also, the Counter and Tamper bytes are written into the first eight bytes of the ‘bitmap’ section of the FileEntry structure. Note that the Counter value reported is the current Counter value. If the counter is a page write cycle counter as in the DS1963, then 1 must be added to the counter value to reflect the upcoming copy.


short far pascal TMCreateFile(

long session_handle,    // session handle for the desired 1-Wire network
void far *state_buffer, // state buffer provided for the 1-Wire network session
short far *maxwrite,    // pointer to short location to put max file size to write
FileEntry far *fentry   // pointer to a structure with the file information
);

For a description of the above types, see the TMEX Type Descriptions.

Parameters

session_handle

Specifies the session handle returned from the API function TMExtendedStartSession that specifies the desired 1-Wire network port. This parameter is required by most TMEX API functions.

state_buffer

Specifies a pointer to a memory location that TMEX keeps all of the state information for the 1-Wire networks. This parameter is required by most TMEX API functions.

maxwrite

Specifies a pointer to a memory location that will contain the estimated maximum file size to write (how much room is left on the part) after returning from the API. The ‘maxwrite’ variable has no meaning until returned by the funtion call (it is an output variable). The maxwrite size may be off by +-28 bytes.

fentry

Specifies a pointer to a memory location that contains a FileEntry structure. This structure must have the name and extension portions set before calling this API.

Return Value

>= 0 => file created, and this is the file handle

<0 => TMEX File Operations Error Return Code

Code Example

See Also

TMWriteFile, TMFirstFile, TMNextFile, TMOpenFile