Ingres CL LO
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - LO
Abstract
This is the specification of the LO facility provided by the compatibility library for "locations" (a system-independent way to represent and manipulate device/directory/file concepts)
Revision: 1.21, 22-Dec-1998
Document History
- Revision 1.21, 22-Dec-1998
- Added definition for previously undocumented LOgtfile() function.
- Revision 1.2, 17-Dec-1997
- Converted to html.
- Revision 1.1, 29-Jul-94
- LOdelete is not recursive (10-Jan-92)
- Revision 1.0, last modified 2-Jul-91
- Added description of LOCATION, LOINFORMATION, LO_DIR_CONTEXT structures missing from previous documentation.
- Noted that the "node" facility of LO is in disuse and should not be relied upon.
- LOwend was changed to have an LO_DIR_CONTEXT argument rather than a PTR, which was inconsistant with its related calls.
- The wording of the description of LOpurge was changed to make it clear that things were being deleted.
- LO_EXE_EXT was added.
- LO_WORK was added for LOingpath.
- LOtos is properly VOID
- Fixed typos.
Specification
Introduction
LO provides client code the ability to:
- manage system-dependent filesystem characteristics
- wildcard-search a directory
Library
CL
Intended Uses
The users of LO routines should not make assumptions about the syntax of a LOCATION. As long as library routines are used to get directory names and also to manipulate them, the routines are guaranteed to work. All storage associated with LOCATIONs must be provided by the caller. All LO routines which require a LOCATION expect the LOCATION to have been initialized by a call to LOfroms, LOcopy, LOingpath or NMloc. The routines LOcreate, LOdelete, LOpurge, LOrename, LOwcard, LOwnext, and LOwend can only be used on SI files.
Obsolete Functions
The following functions are obsolete. They should not be used in new code, and old code should change existing use as opportunity permits.
| Obsolete LO functions | |
| Old function | Replaced with |
|---|---|
| LOlist | LOwcard, LOwnext |
| LOendlist | LOwend |
| LOexist | LOinfo |
| LOisdir | LOinfo |
| LOlast | LOinfo |
| LOsize | LOinfo |
Assumptions
This abstraction assumes a hierarchical filesystem. LOwcard is to be used by front-end code and there is no need at this time to support cross-network directory searches, i.e., it can be assumed that the NODE to be searched is always the machine the executable is running on. It is assumed that there is no "default" separator for the three pieces of the filename dealt with by LOwcard and LOdetail - in particular, "." does not necessarily have to be the separator.
Definitions / Concepts
| location | An actual system-specific object, such as a directory or file. | |
| LOCATION | A datatype used to manipulate filenames in an OS independent manner through the LO routines. | |
| Node | specifies machine, fileserver, or network id. This is in disuse, and may not be relyed upon for access to files or directories on other nodes. | |
| Path | a unique identifier for a directory on a particular machine, including the drive specification. | |
| Filename | the unique identifier for a file within a directory. The "filename" portion of a LOCATION can be split into 3 pieces, any of which may be NULL: | |
| fprefix | that part of the name usually considered to be the actual "name" on systems that maintain file extensions, i.e., the part ahead of the separator. | |
| fsuffix | that part usually called the "extension", e.g., the "qc", "h", or whatever. | |
| version | the version portion of the name for any system which has the concept of file versions (VMS). Otherwise NULL. |
There are some fundamental parameters concerning how filenames look on a given system, which an application may need to know to deal intelligently with naming conventions:
- length of name allowed.
- is extension part of name, or maintained separately by OS. if separate, how long can an extension be?
- Versions maintained / not maintained.
- Case sensitivity.
- Extension to be used with object names. This isn't really a parameter of the OS, but of the linker used in a given environment.
- Extension to be used with executable files.
Header File <lo.h>
The header file <lo.h> must be included before using any of the functions provided. It also defines the following.
LO Constants
| MAX_LOC | the minimum sized char buffer necessary for many LO calls. |
| LO_NM_LEN | maximum filename length. May simply be set to some reasonable value on systems with unlimited or very large filename lengths (BSD UNIX). |
| LO_EXT_LEN | maximum extension length. This value is positive only on systems for which the OS makes a distinction between the extension and the rest of the filename. It is zero on other systems, and the zero value indicates that the extension is actually included in the LO_NM_LEN restriction. If LO_EXT_LEN is positive, it does not count the separator length. |
| LO_OBJ_EXT | a character string which is the extension used for linker objects, (i.e., "o" or "obj"), directly usable by LOcompose as the fsuffix. |
| LO_EXE_EXT | a character string to be used as the extension for executable files, or NULL if no extension is needed, directly usable by LOcompose as the fsuffix. |
| LO_NM_CASE | positive if OS filenames are case sensitive, zero if they are not. |
| LO_NM_VERS | positive if OS supports version information on filenames, zero otherwise. |
LO "what" constants
These are used as arguments to LOingpath and LOingdir.
| LO_DB | database directory. |
| LO_DMP | dump file directory. |
| LO_CKP | checkpoint file directory. |
| LO_JNL | journal file directory. |
| LO_WORK | work (temp) file location used for sorts and the like. |
| Old values DB, DMP, CKP and JNL are no longer supported as they've been replaced with the LO_ prefixed versions above. |
LOCATION - directory/file object structure
The contents of this structure are not visible to client code.
typedef struct
{
. . .
} LOCATION;
LO_DIR_CONTEXT - structure for LOwcard searches
The contents of this structure are not visible to client code.
typedef struct
{
. . .
} LO_DIR_CONTEXT;
LOINFORMATION - output structure for LOinfo
typedef struct
{
i4 li_type;
#define LO_IS_DIR 1
#define LO_IS_FILE 2
#define LO_IS_MEM 3
i4 li_perms; /* the permissions, as bit flags */
#define LO_P_WRITE 0x01
#define LO_P_READ 0x02
#define LO_P_EXECUTE 0x04
i4 li_size;
SYSTIME li_last; /* time of last access */
} LOINFORMATION;
Executable Interface
The following functions are provided.
LOaddpath - add path to a location
Add a head and tail component of a directory path. All arguments (head, tail, and result) should be PATHs. Filenames are appended by LOstfile and LOfstfile. head and result can be the same location -- in this case LOaddpath will add tail to head leaving complete path in head. head and tail must be non-NULL.
Also see:
LOfaddpath, which takes the tail as a string.
Inputs:
| head | Starting location. |
| tail | location being appended |
Outputs:
| result | composite location. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOaddpath(head, tail, result) LOCATION *head; LOCATION *tail; LOCATION *result;
LOchange - change current working directory
Change the current working directory of the current process to LOCATION. Return status.
Also see:
LOgt to determine the current directory.
Inputs:
| loc | The location to make the current default directory |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOchange(loc) LOCATION *loc;
LOcompose - rejoin LOdetail pieces of a name.
Rejoins the pieces of a filename consistently with the way they were separated by LOdetail. If version does not apply on the given system, it is ignored.
Also see:
Inputs:
| dev | device string |
| path | directory string |
| fprefix | filename string |
| fsuffix | extension string |
| version | file version string |
Outputs:
| loc | output location. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOcompose(dev,path,fprefix,fsuffix,fversion,loc) char *dev; char *path; char *fprefix; char *fsuffix; char *version; LOCATION *loc;
LOcopy - Copy LOCATION structure
Copy one LOCATION structure into another. LOcopy will associate the passed in buffer with destloc.
Note: The source LOCATION and the destination LOCATION may be identical.
Inputs:
| srcloc | location to copy |
Outputs:
| destloc | copied location |
| destlocbuf | buffer containing information for destloc. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
VOID LOcopy(srcloc, destlocbuf, destloc) LOCATION *srcloc; char destlocbuf[]; LOCATION *destloc;
LOcreate - Create SI file or directory for SI files
The file or directory specified by dirloc is created. The default mode is owner:rw, group:, world:. If loc is created with the FILENAME flag as part of the specification, then a plain file will be created. If just the PATH flag is specified, then a directlry will be created.
Note: On UNIX, scan permission for the parent directory is needed.
Inputs:
| dirloc | file or directory to create. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOcreate(loc) LOCATION *loc;
LOdelete - Delete SI file or directory of SI files
The file or directory specified by loc is destroyed if possible. If a directory is specified, then all files underneath that directory will also be destroyed. However, nested directories are not deleted.
Inputs:
| loc | directory to delete. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOdelete(loc) LOCATION *loc;
LOdetail - Parse a LOCATION
LOdetail will take a location and character arrays as arguments and fill the arrays with strings which represent various parts of a location. On some operating systems these strings will always be empty strings. In the example of the VMS file string "u$test:[ingres.data]mike.com;2" the following would be the results:
dev: "u$test" path: "ingres.data" fprefix: "mikem" fsuffix: "com" version: "2"
In the example of the Windows NT file string "c:\oping\ingres\data\mike.com" the following would be the results:
dev: "c" path: "\oping\ingres\data" fprefix: "mikem" fsuffix: "com"
Dev refers to file system's device name, while fprefix and fsuffix refer the parts of a filename before and after the last "." of the filename. Buffers are assumed to be big enough to hold LOdetail's output.
Also see:
Inputs:
| loc | The location to examine |
Outputs:
| dev | the device from the location. |
| path | the path from the location. |
| fprefix | the name part of a file |
| fsuffix | the extension part of a file |
| version | the version number of a file |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOdetail(loc, dev, path, fprefix, fsuffix, version) LOCATION *loc; char dev[]; char path[]; char fprefix[]; char fsuffix[]; char version[];
LOendlist - terminate a call to LOlist
LOlist/LOendlist are obsolete. They are replaced by LOwcard, LOwnext, and LOwend.
A call to LOendlist will terminate normally a call to LOlist. This call is made if one wishes to quit reading directories before LOlist returns ENDFILE.
Inputs:
| loc | the location being scanned. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOendlist(loc) LOCATION *loc;
LOexist - does location exist?
LOexist is obsolete. It is replaced by LOinfo.
Does LOCATION loc exist. Returns OK if location exists; otherwise returns a failure status. If the client does not have access permission to this location, the return value is undefined.
Inputs:
| loc | the location in question |
Outputs:
| None |
Returns:
| OK | if the location exists, otherwise system specific failure status. |
Definition:
STATUS LOexist(loc) LOCATION *loc;
LOfaddpath - add a directory to a path
LOfaddpath is like LOaddpath, except the second argument is not a LOCATION containing a path, but it is a string which is the name of a directory to add to the end of the path given by head.
LOfaddpath adds the directory named by the string in tail to the path given by head. Tail can only contain a single directory name. The resulting path is put in the LOCATION result. head and result can be the same location -- in this case LOfaddpath will add tail to head leaving a the resulting path in head. head, tail and result must be non-NULL. Also, the string given by tail must be non-NULL.
The resulting path can be used in other calls to other LO routines, but in particular it can be used in calls to LOcreate. This means the resulting path does not have to exist. In this way, callers can build a path and then create the path.
Also see:
LOaddpath, which takes the tail as a LOCATION.
Inputs:
| head | the leading directory location. |
| tail | the directory string to add. |
Outputs:
| result | Location with the new composite path. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOfaddpath(head, tail, result) LOCATION *head; char *tail; LOCATION *result;
LOfroms - create LOCATION structure from a string
Convert a string to a LOCATION. Buf should be a buffer of MAX_LOC size. The string must be copied into buf before call. The empty string maps to an empty LOCATION. What specifies whether the string describes a node, path, filename or some combination. Choices can be specified with a C '&' operator, with the constants PATH, FILENAME, and NODE.
The use of '&' is surprising, but is necessary instead of the expected C '|' "bitwise-OR" operation that is incorrect.
The buffer associated with a location is owned by LO, not by the caller. On VMS, the string you give LOfroms will be converted to uppercase, logical names will be translated, and a version number will be appended to file names. So, after
STcopy("BIN:LINK.EXE", buffer);
LOfroms(FILENAME & PATH, buffer, &loc);
if BIN is a logical name for DUA0:[PROGRAMS.BIN], buffer will contain "DUA0:[PROGRAMS.BIN]LINK.EXE;0". This has some important consequences:
- The buffer can't be allocated in read-only memory, nor should it be a constant string. It should always be MAX_LOC+1 long, even if you "know" that the filename is shorter than that.
- You can't assume anything about the contents of the buffer after calling LOfroms, whether it succeeds or fails.
- You can't compare your original filename to the LOCATION buffer to see if you have the same file again. The proper way to see if a file is the same as one in a LOCATION is to make a second LOCATION, and compare the buffers. See the example below.
Also see:
LOfroms is the inverse of LOtos.
Inputs:
| what | The type of location being constructed, usually one of: | |
| PATH | a directory | |
| PATH & FILENAME | a fully specified filename | |
| FILENAME | a file in the current default directory. | |
| buf | a buffer containing a null-terminated system specific string representing the location in question. Because it is also an output, it must be at least MAX_LOC in size |
Outputs:
| buf | the input string buffer may be overwritten, and is associated with the constructed location. |
| loc | the constructed location. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOfroms(what, buf, loc) LOCTYPE what; char buf[]; LOCATION *loc;
Examples
LOCATION location; /* LOCATION containing a file */
char *filename; /* file name */
char *locptr; /* "location"s buffer */
LOCATION tmploc; /* temporary LOCATION */
char tmpbuf[MAX_LOC+1] /* temporary buffer */
char *tmpptr; /* temporary pointer */
/* See if "filename" is already pointed to by "location" */
STcopy(filename, tmpbuf);
if (LOfroms(FILENAME & PATH, tmpbuf, &tmploc) != OK)
{
error processing ...
}
else
{
LOtos(&tmploc, &tmpptr); /* Get the LOCATION buffer */
LOtos(&location, &locptr); /* Get the LOCATION buffer */
if (STcompare(tmpptr, locptr) == 0)
{
They're the same ...
}
else
{
They're different ...
}
}
LOfstfile - set file field
Set filename field of a LOCATION. This function is only to be used if filename is internally generated. If the filename is too long then the function will return FAIL, no other error checking is done.
Inputs:
| filename | a string containing the filename to be attached to the location, in native format. |
Outputs:
| loc | the location with the new filename. |
Returns:
| OK | if operation succeeded. |
| FAIL | if anything went wrong. |
Definition:
STATUS LOfstfile(filename, loc) char *filename; LOCATION *loc;
LOgt - get current working directory
Get LOCATION of "current working directory". LOgt will associate buf with the passed location and will overwrite previous contents of loc and buf.
Also see: LOchange to set the current directory.
Inputs:
| None |
Outputs:
| buf | an at least MAX_LOC sized string buffer that will be associated with the location |
| loc | a location filled in with the current default location. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOgt(buf, loc) char buf[]; LOCATION *loc;
LOgtfile - get file name field from LOCATION
Get the contents of the file name field from a LOCATION.
Inputs:
| loc | the source LOCATION |
Outputs:
| fnameloc | a LOCATION containing the file name field from loc |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOgtfile( LOCATION *loc, LOCATION *fnameloc );
LOinfo - get information about a LOCATION
Given a pointer to a LOCATION and a pointer to an empty LOINFORMATION struct, LOinfo() fills in the struct with information about the LOCATION. A bitmask passed to LOinfo() indicates which pieces of information are being requested. This is so LOinfo() can avoid unnecessary work. LOinfo() clears any of the bits in the request word if the information was unavailable. If the LOCATION object doesn't exist, all these bits will be clear.
The recognized information-request bit flags are:
| LO_I_TYPE | what is the location's type? |
| LO_I_PERMS | give process permissions on the location. |
| LO_I_SIZE | give size of location. |
| LO_I_LAST | give time of last modification of location. |
| LO_I_ALL | give all available information. |
Note that LOinfo only gets information about the location itself, NOT about the LOCATION struct representing the location. That's why LOisfull, LOdetail, and LOwhat are not subsumed by this interface.
This interface makes LOexist, LOisdir, LOsize, and LOlast obsolete, and they will be phased out in the usual way. (meaning: they will hang on for years.)
Inputs:
| loc | The location to check. |
| flags | A word with bits set that indicate which pieces of information are being requested. This can save a lot of work on some machines... |
Outputs:
| flags | unavailable information request bits are cleared. |
| locinfo | The LOINFORMATION struct to fill in. If any information was unavailable, then the appropriate struct member(s) are set to zero (all integers), or zero-ed out SYSTIME struct (li_last). Information availability is also indicated by the 'flags' word... |
| flags | The same word as input, but bits are set only for information that was successfully obtained. That is, if LO_I_TYPE is set and .li_type == LO_IS_DIR, then we know the location is a directory. If LO_I_TYPE is not set, then we couldn't find out whether or not the location is a directory. |
Returns:
| OK | if operation succeeded, otherwise system specific error status |
Definition:
STATUS LOinfo(loc, flags, locinfo) LOCATION *loc; i4 *flags; LOINFORMATION *locinfo;
Example:
LOCATION loc;
LOINFORMATION loinf;
i4 flagword;
/% find out if 'loc' is a writable directory. %/
flagword = (LO_I_TYPE | LO_I_PERMS);
if (LOinfo(&loc, &flagword, &loinf) == OK)
{
/% LOinfo call succeeded, so 'loc' exists. %/
if ( (flagword & LO_I_TYPE) == 0
|| loinf.li_type != LO_IS_DIR )
/% error, we're not sure that 'loc' is a directory. %/
if ( (flagword & LO_I_PERMS) == 0
|| (loinfo.li_perms & LO_P_WRITE) != 0 )
/% error, 'loc' might not be writable by us. %/
/% 'loc' is an existing directory, and we can write to it. %/
}
LOingdir - build an Ingres directory name
Produces the lowest-level directory name for a database, journal, or checkpoint directory.
This function is to be used in conjunction with LOingpath(). When LOingpath() is called with a NULL database name, LOingdir() must be called to properly produce the directory name to contain database related files. LOingpath() will perform the same conversion when the database name is provided in the call to LOingpath().
Under most implementations (VMS, UNIX, etc.) LOingdir() may be simply a string copy since there is no conversion performed on the database name. Under more limited filing systems, the dbname and the what parameters are combined to produce a unique directory name which will be the lowest level directory name for this database, journal, or checkpoint path.
Inputs:
| dbname | The name of the database. |
| what | Directory type, one of LO_DB, LO_CKP, LO_DMP, LO_JNL, or LO_WORK. |
Outputs:
| dirname | Buffer to receive the directory name. Length must be at least MAX_LOC. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| LO_NULL_ARG | Bad parameter. |
Definition:
STATUS LOingdir(dbname, what, dirname) char *dbname; char *what; char *dirname;
LOingpath - build INGRES path
Take the values of area, dbname and what and expand them to form the proper fullpath describing the directory specified.
This routine is used to find the locations containing database, checkpoint, journal and dump files.
The area argument is a system dependent string that is stored in the iidbdb. (The interpretation will differ on various systems because of inconsistent directory structures.) The string has a maximum length of DB_MAXNAME characters. This restriction is imposed by client code and the iidatabase catalog, not by LO.
The dbname argument is just a string of the database name, again limited to DB_MAXNAME (24 in release 6; 32 in Ingres 7 & later).
Values for the what argument are LO_DB, LO_DMP, LO_CKP, LO_JNL and LO_WORK
The fullpath argument is the address of a LOCATION that will be filled in with the resolved path.
LOingpath() expands the "II_DATABASE", "II_CHECKPOINT", "II_DUMP", and "II_JOURNAL" symbols (determined by the what string) into the destination location in a system dependent manner. The II_DATABASE etc. symbols are used to locate databases (checkpoints, dumps or journals). These release symbols must be defined in 6.0 or an error will result (previous releases defaulted to the same location as the installation.) These symbols are independent of the areas used by the RODV mechanism.
As mentioned above, the interpretation of the area argument varies because of the different directory structures in use. The nature of the constructed location on the current systems is described below.
On VMS, area is presumed to be the name of a device, and is usually a logical. The concatenation takes the form area::path:dbname where path looks like [ingres.what] No mapping of II_DATABASE is required, since it is mapped by the system when files are opened.
CMS emulates the VMS directory scheme and symbol mechanism. No II_DATABASE mapping is needed.
On UNIX the concatenation takes the forms described below. It is complicated by the baroque nature of the Ingres/UNIX directory structure. In particular, area has three radically different interpretations.
- If the area is a rooted path (limited to DB_MAXNAME characters, as noted above), it is expanded as "/area/ingres/what/default". The "/ingres/" level must be present.
- If the area is one of "II_DATABASE", "II_DUMP", "II_CHECKPOINT", or "II_JOURNAL" then it is interpreted as a special case and uses the ingres NM routines to determine the symbol value for the area name. This area name is used in the iidbdb to specify the default database, dump, journal, or checkpoint area to be used; and that the default area is determined by one of the appropriate environment variables "II_DATABASE", "II_DUMP", "II_CHECKPOINT", or "II_JOURNAL."
Note: The variable II_WORK is reserved for future expansion.
The symbol must be defined as a rooted path with the same characteristics as case 1. If the default location for databases is to be /db_disk, then the value of II_DATABASE must be "/db_disk". The area in this case is expanded to "/db_disk/ingres/data/default". The "/ingres/" level must be present.
- If the area is not a rooted path or one of the special symbols the concatenation takes the form "XXX/ingres/what/area". "XXX" is resolved as follows: If the what requested is one of LO_DB, LO_DMP, LO_CKP, or LO_JNL (but not currently LO_WORK) then NM is used to look up the value of the appropriate symbol for the what requested (e.g. "II_DATABASE" when what is "LO_DB") and it is used as the "XXX" base; it is an error in this case if the appropriate symbol is not set. If the what requested is not one of LO_DB, LO_DMP, LO_CKP, or LO_JNL then the value of II_SYSTEM is used as "XXX".
By setting the area in the iidbdb, the user may place databases (ckp, dumps, journal) on separate volumes. By mounting the volume at the same level as the "default" ones in the default database, dump, journal, and checkpoint locations - $II_DATABASE, $II_DUMP, $II_CHECKPOINT, $II_JOURNAL}/ingres/{data,dmp,ckp,jnl}/default relative "areas" are used. Alternatively, full paths can be used for the "area" by building a separate Ingresdirectory hierarchy (including an "/ingres/" level) on another filesystem, as long as the "area" name is less than DB_MAXNAME characters in length.
Because UNIX does not have the system level symbol mapping of VMS, II_DATABASE etc. must be expanded when the fullpath location is created, rather than deferred to the operating system. The variables must resolve to a full UNIX directory path. II_DATABASE may be used to work around the arbitrary DB_MAXNAME character limit on area names.
Inputs:
| area | a string locating the base path, as described above. |
| dbname | a string containing the name of the database in question. |
| what | one of LO_DB, LO_CKP, LO_DMP, LO_JNL or LO_WORK. |
Outputs:
| fullpath | a location describing the resolved path. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOingpath(area, dbname, what, fullpath) char *area; char *dbname; char *what; LOCATION *fullpath;
LOisdir - is this location a directory?
LOisdir is obsolete. It is replaced by LOinfo.
LOisdir determines whether the dirloc is a directory. dirloc is assumed to contain a full path name. ISDIR is returned in flag if dirloc is a directory. ISFILE is returned if the dirloc is a file.
Inputs:
| dirloc | the location in question. |
Outputs:
| flag | either ISDIR or ISFILE. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOisdir(dirloc, flag) LOCATION *dirloc; i2 *flag;
LOisfull - is this a full path?
LOisfull returns TRUE if loc specifies a full path. On UNIX, this means it starts at '/'. On VMS, it must begin with a device specification. On NT, it either starts with a drive letter, colon and backslash or a double backslash (UNC names).
Inputs:
| loc | the location in question. |
Outputs:
| None |
Returns:
| FALSE | if the location does not represent a fully qualified path. |
Definition:
bool LOisfull(loc) LOCATION *loc;
LOlast - time location last modified
LOlast is obsolete. It is replaced by LOinfo.
Get last modification date of a LOCATION.
Inputs: loc the location in question. Outputs: t filled in with the last time the location was modified. Returns: OK if operation succeeded, otherwise system specific error status.
Definition:
STATUS LOlast(loc, t) LOCATION *loc; SYSTIME *t;
LOlist - List contents of a directory
LOlist/LOendlist are obsolete. They are replaced by LOwcard, LOwnext, and LOwend.
On the first call to LOlist with a given location inputloc (which must be a directory) LOlist opens that directory file and returns the first location in outputloc. On successive calls with the same inputloc LOlist returns the next location in the directory. LOlist will return ENDFILE when called and there are not more locations in the directory. Upon returning ENDFILE LOlist will close the directory file. If one wants to stop the directory list before conclusion call LOendlist. NOTE: the full path is not specified in outputloc. WARNING: LOlist associates a static buffer with outputloc. WARNING: LOlist is only supported for SI files.
Inputs:
| inputloc | location describing the directory to search. |
Outputs:
| inputloc | scanned location context is updated. |
| outputloc | location filled in with the next file in the scan through the inputlocation |
Returns:
| Never returns OK. | |
| ENDFILE | when there is nothing more in the directory to scan. |
| other system specific error status may also be reported. |
Definition:
STATUS LOlist(inputloc, outputloc) LOCATION *inputloc; LOCATION *outputloc;
LOpurge - Purge a directory/file
LOpurge purges (deletes lower-numbered versions from) the files in a directory or the file given by the location loc retaining keep versions. The directory is never removed. If keep equals zero, then all versions are deleted.
If the host OS does not keep multiple versions of files, this call is a no-op unless keep == 0, where it essentially behaves like LOdelete.
Inputs:
| loc | the location to purge. |
| keep | the number of versions to keep; if 0, then all versions are deleted. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOpurge(loc, keep) LOCATION *loc; i4 keep;
LOrename - rename SI file
Rename the file specified in oldfname to newfname. LOrename can not be used to relocate a directory nor can LOrename move a file from one directory to another. It can only rename a file in-place.
Inputs:
| oldfname | A location describing the current file. |
| newfname | A location in the same directory describing the new file. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects
| The file in question is renamed. |
Definition:
STATUS LOrename(oldfname, newfname) LOCATION *oldfname; LOCATION *newfname;
LOsize - get location size
LOsize is obsolete. It is replaced by LOinfo.
Get LOCATION size in bytes. The size is approximate only. The size returned may be larger than the actual number of bytes in the file.
Inputs:
| loc | the location in question. |
Outputs:
| loc_size | the approximate size of the location. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOsize(loc, loc_size) LOCATION *loc; i4 *loc_size;
LOstfile - set file field
Copy the filename field of LOCATION filename to the filename field of LOCATION loc.
Inputs:
| filename | a location with a filename to be used in the output location. |
| loc | a location possibly containing a path and a filename that will be replaced. |
Outputs:
| loc | a location modified with the filename part of the input location. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOstfile(filename, loc) LOCATION *filename; LOCATION *loc;
LOtos - LOCATION to string
Convert a LOCATION to a string. Sets string to point to buffer which contains text of location in string form.
Also see:
This is the inverse of LOfroms.
Inputs:
| loc | the location to examine. |
Outputs:
| string | a buffer of at least MAX_LOC in size that will be filled in with a system specific string representing the location. |
Returns:
| none |
Definition:
VOID LOtos(loc, string) LOCATION *loc; char **string;
LOuniq - make unique LOCATION for a temp file
The string pat is prepended to a 6 character alphanumeric pattern guaranteed (with respect to calls of LOuniq in other processes) to be unique. If the suffix argument is not NULL then the suffix (which should be 3 or fewer characters) will be concatenated to the end of the temporary file name. A suffix "tmp" will result in a filename of the form "patXXXXXX.tmp". If the resulting filename would exceed OS filename length limits, then the function will shorten the pattern to the necessary length by truncating pat. The resulting filename is located in directory path. The file or directory of the given name is not actually created. A null path means use the current process path.
Inputs:
| pat | prefix to a 6 character string that will be used to generate a unique filename. |
| suffix | an extension to be appended to make the new name. |
Outputs:
| loc | a location describing a unique file |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOuniq(pat, suffix, path) char *pat; char *suffix; LOCATION *path;
LOwcard - limited wildcard directory search
Begin limited wildcarding directory search. The arguments are similar to those in LOdetail(). loc must contain the path portion of the name. The fprefix, fsuffix and version may be specified, or NULL to indicate wildcarding. This search is limited to SI files. If version is not applicable on a given OS, that argument is ignored.
The LO_DIR_CONTEXT argument points to an instance of that structure which must be maintained in memory across all the succeeding calls to LOwnext, LOwend associated with it. In short, if allocated, it can not be freed until after the LOwend call, and if on the stack, the associated LOwend must be called before returning from the procedure which declared it. The same applies to the memory pointed to by the fprefix, fsuffix and version (if applicable) arguments. It is legal for LO_DIR_CONTEXT to only maintain pointers to these strings, if needed.
Inputs:
| loc | Location describing a directory to search. |
| fprefix | filename prefix or NULL to wildcard. |
| fsuffix | file extension or NULL to wildcard. |
| version | as for LOdetail, NULL to wildcard. |
Outputs:
| loc | First name in list. |
| lc | Context pointer for LOwnext, LOwend. |
Side Effects:
| May "open" a directory or some such operation. |
Definition:
STATUS LOwcard(loc,fprefix,fsuffix,version,lc) LOCATION *loc; char *fprefix; char *fsuffix; char *version; LO_DIR_CONTEXT *lc;
LOwend - end directory search
Used to close a search initiated with LOwcard. Further calls on that context block are illegal.
Note: versions prior to LO 1.0 had the "lc" argument as a PTR; this was inconsistant with LOwcard and LOwnext.
Inputs:
| lc | Context block pointer from LOwcard |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| May "close" a directory, or some such operation. |
Definition:
STATUS LOwend(lc) LO_DIR_CONTEXT *lc;
LOwhat - what parts does a LOCATION have?
What combination of NODE, PATH, and FILENAME are in the LOCATION. Returns boolean AND. LOwhat returns what it thinks the LOCATION is -- it does not do system tests on the location.
Inputs:
| loc | the location to be examined |
Outputs:
| loctype | filled in with NODE, PATH, FILENAME as appropriate. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LOwhat(loc, &flag) LOCATION *loc; LOCTYPE *flag;
LOwnext - next file in directory
Return next file in directory, or ENDFILE.
Inputs:
| lc | Context block opened at LOwcard call. |
Outputs:
| loc | Next file. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| ENDFILE | if there is nothing more to be seen in the directory. |
Definition:
STATUS LOwnext(lc,loc) LO_DIR_CONTEXT *lc; LOCATION *loc;
Examples
# include <lo.h>
......
LO_DIR_CONTEXT lc;
LOCATION loc;
STATUS rc;
<set up PATH portion of loc>
if (LOwcard(&loc,NULL,"c",NULL,&lc) != OK)
<error handling>
while ((rc = LOwnext(&lc,&loc)) == OK)
{
<extract and print filename string>
}
if (rc != ENDFILE)
<error handling>
_VOID_ LOwend(&lc);
The above might be what you would do to print out all the .c files in a directory.
LOwend returns a status, but will probably have no particular recovery operation
for failure in many cases.
Making ING_LIB the current directory
change_to_inglib()
{
char *str;
LOCATION loc;
char loc_buf[MAX_LOC];
NMgtAt(ING_LIB; &str);
if (str == NULL || *str == EOS)
return(FAIL)
STcopy(str,loc_buf);
LOfroms(PATH, loc_buf, &loc);
LOchange(&loc);
return(OK);
}
|
Ingres Compatability Library |
