|
<< Click to Display Table of Contents >> Navigation: Concordance Programming Language Reference > Functions > R |
The following topic discusses the Concordance Programming Language (CPL) functions that begin with the letter R. For more information on CPL functions, see Functions, About the Advanced Programming Features, and About CPL Functions.
int rand([int seed]); |
•Description - Creates a random number sequence for any given seed number. The sequence will always be the same for a particular seed number. rand() should be called with a seed value to begin the random number sequence, for instance, rand(clock()). From then on it will return random numbers.
•Return Value - Zero when called with a seed value. A random number otherwise.
•Version - Version 6.0 and later
int read(int handle; char buffer[]; int length); |
•Description - Reads length bytes from the file referenced by handle into the variable buffer. You can read/write numeric values by passing their names and using the sizeof() function to determine their lengths.
•Return Value - Returns the number of bytes read, which may be less than that requested if the end-of-file was encountered during the read.
•See Also - readln(), readc(), write(), writeln(), open(), close()
Example
copyfiles(text from, to) { char buffer[512]; int i, oldfile, newfile; /* Open the old file, in read only mode. */ if ((oldfile = open(from,"r")) < 0) return(-1); /* Now open the new file, create it. */ if ((newfile = open(to,"w+")) < 0) { close(oldfile); return(-1); } /* Copy the old file to the new file. */ while((i = read(oldfile,buffer,512)) > 0) write(newfile,buffer,i); close(oldfile); close(newfile); return(0); } |
int readc(int handle) |
•Description - Retrieves one byte from the file referenced by handle. Handle must be a value returned by a call to open().
•Return Value - Character read from file, or -1 if end of file encountered.
•See Also - open(), close(), writec(), read(), readln()
Example
skip(int handle) { int c, EOF, LF; /* Skip past one line of input. Read ** until the end-of-file is encountered, ** or a line feed is found. */ EOF = -1; LF = 10; c = 0; while((c <> LF) and (c <> EOF)) c = readc(handle); } |
int readdoc(int db, document); |
•Description - Reads the document from the database. The document becomes the current document. This function does not use the query list, but reads the document in the underlying database. If the current query contains 3 documents, and you request
readdoc(db, 100); |
othen the 100th document in the database is read.
oUsing next() after this command will retrieve the next document in the query, not document 101. The same goes for prev(), both functions work on the current query.
•Return Value - A -1 if the document is out of range.
•See Also - recno()
int readln(int handle; char buffer[]); |
•Description - Reads one line of text from the file referenced by handle. The read continues until a line feed is encountered, carriage returns are ignored. The text is stored in the buffer without the terminating line feed. If the buffer fills before the full line is read, then the partial line is returned. The buffer is terminated with a zero.
•Return Value - The number of characters read, without counting carriage returns and line feeds. A -1 indicates an attempt to read beyond the end of the file, the buffer will not contain any characters in this case.
•See Also - writeln(), read(), write()
recall(int db); |
•Description - The current document is unmarked for deletion.
•Return Value - None.
•See Also - delete()
Example
main() { int db; if ((db = opendb("recipes")) <> 0) { /* Recall all documents from deletion. */ cycle(db) recall(db); closedb(db); } } |
int recno(int db); |
•Description - Retrieves the physical record number of the current document. This function does not use the current query. recno() can be used with readdoc(). Both readdoc() and recno() ignore the current query and operate on the underlying database.
oA related function, docno(), always returns information from the current query. Using docno() after readdoc() will cause the current document in the query set to be read. The document read by readdoc() will be flushed.
oUse docno() with the functions that manipulate queries, i.e. first(), last(), next(), etc. recno() can be used with either readdoc() or the query functions.
•Return Value - The current document's physical record number, or a value less than or equal to zero if no document is ready, i.e. after a blank(), or if the database is empty.
•See Also - readdoc(), docno()
int reindex(int database); |
•Description - The database is reindexed. reindex() will call index() if the database has not yet been indexed. The screen is automatically saved before entering this mode and restored after exiting.
•Return Value - Zero if successful.
•See Also - index()
int rename(char oldname[], newname[]); |
•Description - The file name is changed from oldname to newname.
•Return Value - A return value of -1 indicates an error. Errors are caused by a failure to find the file, a poorly formed DOS file name, or a file that already exists with the new name.
text rep(char ch | text string; int length); |
•Description - Creates a new string with the character ch or text string repeated length number of times.
•Return Value - A text variable.
Example
DrawLine(int row; char ch); { /* Draw a line across the screen. */ puts(row, 0, rep(ch,80), TextHighlight_); } |
int replicate( int publisher; text subscriber; text synchMethod; int appendToPublisher; int appendToSubscriber; text deletionTag; int copyDeletionMarks; int restoreDeletedDocs; text collisionTag; int copyAttachments); |
•Description - Synchronizes two database. The databases must be from the same replication set, for instance they were created from the same databases using createReplica(). Security, record edits, deletions, and tags are replicated. Replication does not reindex or pack the databases.
oConcordance will attempt to open the subscriber database in shared, multi-user mode. This enables laptop clients to synchronize with the network database even if they are running a single user. However, if the single user program already has the database open on the File menu, the shared open will fail. The example program takes this into account by closing any open database handles.
oreplicate() can synchronize all fields or just selected fields. Use the db.order[i] value to select fields for replication. Only selected fields are replicated. See the example for more information.
oAny records in collision are tagged with the collisionTag. A collision occurs when the same field in the same record in both databases has been edited. Concordance will not overwrite either edit, but will flag the records as being in collision. See the resolve() function for information on scripting collision resolution.
Parameter |
Type |
Function |
publisher |
int |
Handle of publisher database. |
subscriber |
text |
Full path and file name of subscriber database. |
synchMethod |
text |
Specify one of the three following options for synchronization: "Synchronize" for full bi-directional synchronize between databases. "POverwrites" for the publisher to overwrite the subscriber when differences are detected, regardless of which database has the most up-to-date information. "Soverwrites" for the subscriber to overwrite the publisher when differences are detected. |
appendToPublisher |
int |
Pass any nonzero value to allow appending of new records to the publisher from the subscriber. Use zero to prevent appending of new records to the publisher database. This is a Boolean value. |
appendToSubscriber |
int |
Pass any nonzero value to allow appending of new records to the subscriber from the publisher. Use zero to prevent appending of new records to the subscriber database. |
deletionTag |
text |
The optional tag is applied to records when the flag marking a record for deletion is copied from one database to another. Use "" if you do not want to tag these records. |
copyDeletionMarks |
int |
Use any nonzero value to allow replication to copy deletion flags. This flag indicates that a record should be deleted during the next database pack. It does not delete the record during replication. |
restoreDeletedDocs |
int |
Use any nonzero value to restore deleted records. This restores the record if it exists in one database but has been deleted from the other. Note that it may be restored and still flagged for deletion. |
collisionTag |
text |
This tag is applied to records in each database when a collision occurs. Use this tag after replication to resolve collisions via the resolve() function. Use "" if you don’t need to track collisions. |
copyAttachments |
int |
This optional parameter copies attachments if set to TRUE. |
•Return Value - A zero indicates success. Any nonzero value indicates failure. Failure can occur if the subscriber database cannot be opened, if the databases are not from the same replication set, if the replication fields are not present or are not both system and key fields.
Example
/* Fragment of code to synchronize two databases. ** The user’s ID and date are used to flag any ** collisions. The tag could be used later to ** resolve the collisions with resolve(). */
int i, TRUE = 1, FALSE = 0; /* Replicate every field. This is a required step. */ for (i = 0; i <= db.fields; i = i + 1) db.order[i] = i; replicate( db, "\\CloudNine\Nome\Alaska\Catalog.dcb", "Synchronize", TRUE, /* Append to publisher. */ FALSE, /* Don’t append to subscriber. */ "", /* Don’t tag deletions. */ TRUE, /* Replicate deletions. */ FALSE, /* Don’t restore deletions. */ netuser() + " " + dtoc(today()); |
•See Also - createReplica(), resolve()
int report(int db; text reportName; int first, last); |
•Description - Runs the named report for the document range. The report is sent to the current default printer.
•Return Value - Zero if the report ran, nonzero otherwise.
Example
MonthlyReport(int db) { char szNow[10]; int rc;
/* Print a report for every record this month */ if (db.documents > 0) { szNow = str(month(today())) + "/??/" + str(year(today())) search(db, "DATE = " + szNow); if (count(db) > 0) { sort(db, "dtoc(db->DATE, 'Y')"); rc = report(db, "C:\concord5\taxs.arp", 1, count(db)); } } return(rc); } |
•See Also - print(), printfs(), reportfs()
•Version - Version 6.0 and later.
reportfs(int db); |
•Description - Invokes the Concordance full screen report writer. The screen is automatically saved before entering this mode and restored after exiting.
•Return Value - None.
reset(int db); |
•Description - Resets the current document, reloading the record from disk without saving any changes made by the programming language application. Note that a call to any full screen function, such as browse() or editfs(), will automatically save the edits. The database functions, next(), prev(), etc., will also save the edits.
•Return Value - None.
int resolve(int toDatabase, fromDatabase); |
•Description - This function is passed handles to two databases. It resovles a collision between records in these databases by copying all fields from one database to another database, making the records identical and eliminating the collision.
oCollisions occur when the same field in the same record has been edited in both the subscriber and publisher databases. Since Concordance cannot determine which edit is the "correct" edit, it flags these records as being in collision.
oThe resolve() function is used to automate replication. It provides a powerful mechanism to script collision resolution based on edit dates, user log-in name, and other user criterion stored in the replication fields.
•Return Value - A zero signifies success.
Example
/* Fragment of code to synchronize two databases ** and resolve any collisions between them. */
int i, dbS, TRUE = 1, FALSE = 0; text szTag; /* Tag used to locate collisions. */ char string[200]; /* Used to create a search string. */
/* Replicate every field. This is a required step. */ for (i = 1; i <= db.fields; i = i + 1) db.order[i] = i;
/* Create a unique tag for collisions */ szTag = netuser() + " " + dtoc(today());
/* Replicate the databases, tagging any collisions. */ replicate( db, "\\Williamson\case\Production.dcb", "Synchronize", TRUE, /* Append to publisher. */ TRUE, /* Append to subscriber. */ "", /* Don’t tag deletions. */ TRUE, /* Replicate deletions. */ FALSE, /* Don’t restore deletions. */ netuser() + " " + dtoc(today());
/* Databases are replicated. Now handle collisions. */ /* First open the subscriber database. */ if ((dbS = opendb("\\Williamson\Case\Production.dcb")) >= 0) { /* We need to see the system fields used for */ /* replication. Make them visible to us. They */ /* link the records in the databases. */ set(db, "System fields", "Show"); set(dbS, "System fields", "Show");
/* Locate all records in the publisher database */ /* that were tagged for collision, then process. */ tagquery(db, szTag);
/* Loop through the tagged collision records. */ cycle(db) { /* Find this record in the subscriber. */ string = ‘CREATIONID = "’+trim(db->CREATIONID) + chr(‘"’); if ((search(dbS, string) == 0) and (count(dbS) > 0)) { /* We found the record. For the example */ /* we will keep the NOTES field from the */ /* publisher database, and use all other */ /* fields from the subscriber database. */ dbS->NOTES = db->NOTES; resolve(db, dbS); } }
/* Clear the temporary tags we used for collisions. */ tag(db, -1, szTag); tag(dbS, -1, szTag);
/* Close the subscriber, we’re done */ closedb(dbS);
/* Hide the system fields, we’re done. */ set(db, "System fields", "Hide");
} |
•See Also - createReplica(), replicate()
restore(row, column, text screen); |
•Description - Places the screen image on the screen that was previously created by a call to the save() function. The image is placed at the location whose upper left corner is described by the row and column coordinates.
•Return Value - None.
•See Also - save()
int rmdir(text directoryPath); |
•Description - Removes (deletes) the specified directory. The directory must not contain any files or subdirectories. directoryPath can be either an absolute path name or relative to the current working directory.
•Return Value - rmdir returns zero if successful, -1 otherwise.
•See Also - chdir(), getcwd(), mkdir(), rename(), erase()
float round(float number; int decimals); |
•Description - Rounds the fractional portion of a floating point number to the specified number of decimals.
•Return Value - The rounded floating point number.
Example
main() { float f, pi; pi = 3.1459; f = round(pi,2); /* f now contains 3.15 */ ... } |
text rtrim(text string); |
•Description - Removes all trailing white space from the text variable, character array, or field. White space consists of spaces, tabs, carriage returns, and line feeds.
•Return Value - Returns a duplicate of the string, does not modify the original.
•Version - Version 6.0 and later
run(text program, function); |
•Description - This function is used to execute external CPL programs. The program parameter is the name of a .CPL or .CPT file which contains the function. Inclusion of the .CPL or .CPT file name suffix is optional.
oThe called function can access and change any globally declared variable in the calling program. It can also execute any function in its own file or in the calling function's file. Global variables declared in the called module are only accessible while the module is loaded and running. Functions and variables in the module will replace pre-existing functions and variables of the same name.
oQuoted strings that are used as parameters should be assigned to a text or char array before being passed. See the example below.
•Return Value - The value returned by run() is the value returned by the function that is executed. It can be any Concordance value.
•See Also - eval()
Example
LoadSpeller(int db) { char prompt[50]; int ok; /* Load an external program to spell check. */ prompt = "Look up word: "; if (ok = run("spellchk.cpl","Check(db,prompt)")) { prompt = "Enter correction: "; ok = run("spellchk.cpl","Correct(db,prompt)"); } return(ok); } |