FairCom ISAM for C

GetCtTempFileName

Create a file name that is guaranteed to be unique. Can also specify the path for the creation of temporary files.

Short Name

TMPNAME()

Type

Low-level function

Declaration

COUNT GetCtTempFileName(pVOID bufptr, VRLEN bufsiz)

Description

GetCtTempFileName() by default returns a unique file name in the parameter bufptr. Set bufsiz to the length of the buffer at bufptr, minimum 10 bytes.

Three c-tree configuration settings influence how GetCtTempFileName() functions:

ct_tmppth -- A c-tree global variable to set the temporary files directory path in standalone operation.
TMPNAME_PATH -- A FairCom Server configuration keyword specifying a directory name to use for the temporary files.
USERPRF_PTHTMP -- An initialization parameter to InitCTreeXtd() toggling the functionality of the GetCtTempFileName() operation. When specified, bufptr specifies the temporary file directory, and must be nul terminated.

The usage of this function varies by c-tree model and how you configure these three c-tree operational values.

Standalone Usage

To specify a directory name where temporary files are to reside in the standalone model set the global variable, ct_tmppth, to the path desired.

Previously, the user profile mask, USERPRF_PTHTMP, was documented for use in the InitCTreeXtd() call. This use of USERPRF_PTHTMP in standalone mode should be considered legacy support. Setting the path with ct_tmppth is the FairCom recommended approach in standalone mode.

Client Server Usage

The client-server model becomes more complicated as there are two values to consider. The FairCom Server allows specifying a directory name with the TMPNAME_PATH server configuration keyword. In addition, the user profile mask, USERPRF_PTHTMP, will change the behavior of the GetCtTempFileName() function to allow setting the temp path directory location.

In the client-server model, the user profile mask takes precedence over the TMPNAME_PATH server configuration setting. Together, the combination of these two settings determine the action taken by the FairCom Server.

The following table summarizes the behavior of GetCtTempFileName():

Table 6-5:

ctsrvr.cfg TMPNAME_PATH	user profile bit USERPRF_PTHTMP	Behavior
0 (undefined)	0 (undefined)	Returns a unique file name in bufptr using the system’s temporary file routine and the FairCom Server’s default path.
0 (undefined)	1 (defined)	Returns a unique file name in bufptr using the system’s temporary file routine and the path specified by bufptr. bufptr must be nul terminated.
1 (defined)	0 (undefined)	Returns a unique file name in bufptr using the system’s temporary file routine with the path specified in the configuration file.
1 (defined)	1 (defined)	Returns a unique file name in bufptr using the system’s temporary file routine and the path specified by bufptr. bufptr must be nul terminated.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error.
17	DCRAT_ERR	Bad input path specified in bufptr.
153	VBSZ_ERR	Buffer too small for temporary name.
155	SYST_ERR	Native system’s temporary file routine failed.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example Standalone Usage

#define MAX_SIZE 255

TEXT temp_path[MAX_NAME] = "/usr/fairtemp/";

pTEXT path_buffer;

if (InitISAMXtd(32, /* index buffers */

12, /* files */

8, /* # 128 bytes sectors */

32, /* data cache pages */

0, NULL,NULL,NULL)) {

printf("\nCould not initialize FairCom DB\n");

exit(2);

}

/* Allocate buffer for temporary file path. */

if (!(ct_tmppth = mballc(1, MAX_SIZE)))

printf("Error: Failed to allocate %d bytes for temp path buffer\n",

MAX_SIZE);

/* Allocate buffer for temporary file buffer. */

if (!(path_buffer = mballc(1, MAX_SIZE)))

printf("Error: Failed to allocate %d bytes for temp path buffer\n",

MAX_SIZE);

/* Specify the path /usr/fairtemp/ for temporary files */

strncpy(ct_tmppth, temp_path, MAX_SIZE);

/* Request a temporary file name */

if(GetCtTempFileName(path_buffer,200L)) {

printf("\nError on GetCtTempFileName, uerr_cod =%d", uerr_cod);

exit(2);

}

printf("\nUsing temporary pathname: %s\n", path_buffer);

/* Done with temp path buffers, so free them. */

if (ct_tmppth) {

mbfree(ct_tmppth);

ct_tmppth = NULL;

}

if (path_buffer) {

mbfree(path_buffer);

path_buffer = NULL;

}

CLISAM();

Client Server Usage with USERPRF_PTHTMP

#define MAX_SIZE 255

TEXT temp_path[MAX_NAME] = "/usr/fairtemp/";

pTEXT path_buffer;

if (InitISAMXtd(32, /* index buffers */

12, /* files */

8, /* # 128 bytes sectors */

32, /* data cache pages */

USRPRF_PTHTMP, /* GetCtTempFileName sets path */

"ADMIN","ADMIN","FAIRCOMS")) {

printf("\nCould not initialize FairCom DB\n");

exit(2);

}

/* Allocate buffer for temporary file path. */

if (!(path_buffer = mballc(1, MAX_SIZE)))

printf("Error: Failed to allocate %d bytes for temp path buffer\n",

MAX_SIZE);

/* Specify the path /usr/fairtemp/ for temporary files */

strncpy(path_buffer, temp_path, MAX_SIZE);

/* Set the temporary file name */

if(GetCtTempFileName(path_buffer, MAX_SIZE)) {

printf("\nError on GetCtTempFileName, uerr_cod =%d", uerr_cod);

exit(2);

}

printf("\nUsing temporary pathname: %s\n", path_buffer);

/* Done with temp path buffer, so free it. */

if (path_buffer) {

mbfree(path_buffer);

path_buffer = NULL;

}

CLISAM();

Limitations

If a client process on a heterogeneous network sends a GetCtTempFileName() path with an improper directory separator, GetCtTempFileName() returns an error, since the name will not be well defined, instead of automatically changing the separators to match the Server conventions.