PMDF popstore & MessageStore Manager's Guide
Previous Next Contents Index

POPSTORE_format_read

Read and parse a formatting file.
FORMAT 


int POPSTORE_format_read (format, fname, fname_len, path, 
                          path_len) 
      POPSTORE_format_element **format; 
      char                     *fname; 
      int                       fname_len; 
      char                     *path; 
      int                       path_len;

Arguments

format

Pointer to a formatting context generated by reading and parsing the specified formatting template file. Dispose of the context by calling POPSTORE_format_dispose. Used for output only.

fname

Name of the formatting template file to read. Used for input only.

fname_len

Length in bytes of the formatting template file, fspec. Used for input only.

path

Full directory path to the directory containing the formatting template file. Used for input only.

path_len

Length in bytes of the directory path, path. Used for input only.

Description

Before calling any of the other POPSTORE_format_ subroutines, you must first have processed a formatting template file with POPSTORE_format_read. This will generate a formatting context which can then be used with the other POPSTORE_format_ subroutines. When finished using a formatting context, dispose of it with a call to POPSTORE_format_dispose. The name of the formatting file is specified with the fname argument. The directory path leading to the file is specified with the path argument.3 Formatting files are described throughout Chapter 4; see Section 4.3.2 for basic information on formatting files. The particular substitution strings permitted in a formatting file will depend upon the intended usage of the formatting file; i.e., depends upon which POPSTORE_format_ subroutines it will subsequently be used with.

Return Values

POPSTORE_SUCCESS Normal, successful completion.
POPSTORE_BADARG File name argument, fname, is null, or file name length, fname_len, is zero.
POPSTORE_ILLFILE Directory path and file name result in an illegal file specification; note that the directory path must be specified and must have a non-zero length.
POPSTORE_TOOLONG Directory path and file name result in a file specification whose length exceeds 1024 bytes.
POPSTORE_FILOPNERR Unable to open the formatting file.
POPSTORE_VMERROR Insufficient virtual memory.

Note

3 These two parts of the full file path are specified independently so as to simplify the coding of servers which need to ensure that formatting files are read only from a specific directory tree and not from any user-specified location.

Previous Next Contents Index