This chapter describes and provides examples of REQL functions that are used to query and manage Revolve projects.
Functions are designed to handle special tasks, often corresponding to features available in the Graphical User Interface. The functions that are only available to administrators in shareable projects are designated with an asterisk (*).
The activate function opens the specified feature in the Revolve desktop.
integer activate(string [,set])
Open program Browser
activate("programbrowser");
The addComponent function adds components to the active project. The component path and file name must be specified. If the component is already included in the project, it will not be added. The path and file name should not include wildcards.
addComp(string[,type])
To add the bms component named "intro.bms" to the current project:
addComponent ("C:\product\samples\sampleapp\bms\pp1.bms");
* In shareable projects this function is exclusive to the administrator.
This function adds the spcified files from the specified directory.
addDirectory(strpath, strfilespec,(0|1)[,type])
| strpath | path to the directory that contains the files you want to add to the open project |
| strfilespec | names or name patterns of the files you want to add to the open project |
| 0 | do not recurse subdirectories |
| 1 | recurse subdirectories |
| type | Revolve type [optional] |
The addEntity function adds an entity or database element to the REQL database. It accepts an object name and a type for that object and returns the object.
addEntity("entity-name", type)
New entity added to the database.
To add a user-defined file to the Revolve database:
addEntity("PROD.MY.FILE",
type="system_data_file");
The addExtSource function adds an extension to the project's automatic extension list. Files with the new extension are added as the specified type when automatic typing is selected.
addExtSource(string, type)
1=successful 0=error
To relate .DEC as a DEC COBOL program:
addExtSource(".DEC",type=system_component_cobol_dec);
* In shareable projects this function is exclusive to the administrator.
The addPathDb function adds a common database search path.
addPathDb(string)
1=successful 0=error
To add a common database search path:
addPathDb("c:\product\bin\projects\");
* In shareable projects this function is exclusive to the administrator.
The addPathSource function adds the specified path to the project.
addPathSource(string, type, {1|0})
| 1 | include this to turn on scanning |
| 0 | include this to add the search path to the specified component, exclude it to add the search path at component level |
1=successful 0=error
To add a search path for COBOL components:
addPathSource("c:\product\samples\sampleapp\cobol\",
type="system_component_cobol");
* In shareable projects this function is exclusive to the administrator.
The addRel (addRelation) function adds a relationship between two entities in the database.
addRel(elemfrom, relation, elemto|string|number)
1=successful 0=error
To relate an assignfile to a data file:
addRel(system_cobol_assign_file="PLAYMSIO", relation="alias_for_file", system_data_file="PROD.PLAY.MASTER");
Note: When adding a relation with the addRel function, both the source and destination objects must exist within the database. To create new objects use the addEntity() function.
The addSearchExclusion function adds a regular expression to the search exclusion list of components. Components matching any expression in the exclusion list will not be added to the project with the Automatic Component Locator.
addSearchExclusion(string)
To ensure that online programs are not added to the project with the Automatic Component Locator:
addSearchExclusion("ONLINE*.CBL");
* In shareable projects this function is exclusive to the administrator.
The addtoAnnotation function adds the allocated sets of elements to an open annotation.
addToAnnotation(set)
1=successful 0=error
To add a set of "if" statements to the current annotation:
addToAnnotation(cobol_state_if,0);
Adds a new tool to Tools menu.
addTool(toolName, toolCommand)
1=successful 0=error
To add a notepad to the tools menu:
addTool("notepad","C:\WINDOWS\NOTEPAD.EXE{%F}");
The ask function initiates a prompt dialog where the user must answer yes or no in order to continue.
ask(string)
If "Yes" is chosen, 1 is returned.
If "No" is chosen, 0 is returned.
If (ask("Do you wish to continue ?")==1){..}
The atoi function accepts a string of numbers and returns the corresponding integer representation.
atoi(string)
corresponding numbers
currentyear := atoi("1997")
The changestring function changes all database references from the old string to the new string. This is especially useful when source code is moved from one disk location to another and all of the internal database references to the source code must be maintained. Only available to the administrator.
changestring(strFrom, strTo)
changeString("C:\product\source\",
"R:\acsrc\");
* In shareable projects this function is exclusive to the administrator.
The checkMessage function checks for any user-to-user messages that have been received.
checkmessage()
1=successful 0=error
The checkSystem function returns as 0 if Systemwide database has been corrupted; 1 if otherwise.
checksystem()
1=successful 0=error
* In shareable projects this function is exclusive to the administrator.
The chooseComponents function opens a Choose Components dialog which displays all component elements of the specified set. If an element in the set is not a component it is translated to the encompassing component.
chooseComponents(set)
Set of components selected
To allow user to select a set of cobol components:
scope:=all; vComponents:=chooseComponents(system_component_cobol);
The chooseElements function opens a Choose dialog which displays all elements of the specified set and allows for the selection of one or more of the listed elements. When the Choose dialog is closed the selected elements are returned to their respective locations.
chooseElements(set)
Set of selected elements
To allow user to select set of files:
vFiles :=chooseElements(system_data_file);
The clearHighlights function unhighlights the specified element, set, variable, and color.
clearhighlights(set|string)
To clear the color "yellow" from any open tools or views:
clearHighlights ("yellow");
To unhighlight all highlights:
clearHighlights ("all");
The close command closes the active shell.
close(integer);
open shell;
close;
The compile function uses the REQL script specified as an input file (.RQS) to generate a compiled output file (.RQC). You can use the COMPILE command to compile the script before using INVOKE to execute it.
compile(inputFilename [ , outputFilename]);
compile("anno4.rqs", "anno4.rqc");
The compress function compresses project files.
compress()
* In shareable projects this function is exclusive to the administrator.
The compressComps function compresses the specified set of components in the local databases.
compressComps(set)
To compress all COBOL programs:
scope :=all; compressComps(system_component_cobol);
* In shareable projects this function is exclusive to the administrator.
The convertDate function takes a UNIX date format integer and returns a displayable string.
convertDate (integer)
| integer | the date in UNIX date format |
newString:=convertDate (1027602393)
gives you "Thursday, July 25, 2002, 02:06:33 PM"
newString:=convertDate (project:>lastupdate)
The count function returns the number of elements in the specified set.
count(set)
Number of elements in the specified set
To show the number of elements in a set consisting of the numbers 5 and 3:
show "The number of elements is ",count((5&3));
Yields:
2
The createSourceCache function copies the Revolve source files in the input set to a directory.
createSourceCache(setIn, directory[, FlattenPath (0/1)][, PrintOnly (0/1)])
| setIn | set containing the revolve IDs of the source files you want to copy. The IDs must be a subtype of system_code |
| directory | name of the target directory (quoted string) |
| 0 | (default) Preserve the directory paths of the copied files (target dir\subdir1\subdir2\subdir3\file.ext) |
| 1 | flatten the file paths to dotted names (target dir\subdir1.subdir2.subdir3\file.ext) |
| 0 | (default) Copy files and print results to the REQL shell |
| 1 | do not copy; only print files that would have been copied to the shell |
Copy the source files in the input set, using flattened paths:
createSourceCache(setIn, "C:\MyOutput",1)
Use the same options, but don't copy the files: just echo the names to the REQL shell:
createSourceCache(setIn, "C:\MyOutput",1,1)
The deleteRel function deletes the user relation between the specified two entities in the database.
deleteRel(entity-from, relation, entity-to|string|number)
To remove an alias from a COBOL assign file to a datafile:
deleteRel(system_cobol_assign_file="PLAYMSIO", relation="alias_for_file",system_data_file="PROD.PLAY. MASTER");
* In shareable projects this function is exclusive to the administrator.
The div function returns the quotient from the division of the first number by the second number through integer division.
div(number, number)
show div(15,2); 7
The execute function allows you to run other executable programs from Revolve. There is no synchronization between the started program and the execute function.
execute(command, {0|1|2}, seconds)
| command | the path to the executing item |
| 0 | executes the command without halting script |
| 1 | executes the command and halts script until executable is finshed |
| 2 | execute the command and waits the specified number of seconds before returning. |
| seconds | number of seconds before return. Only applies if Option 2 is used. |
1=successful 0=error
To execute copyfiles.bat:
execute("c:\copyfiles.bat", 0)
The script executes without delay.
execute("c:\copyfiles.bat", 1)
The script halts execution until the batch file has been executed.
execute("c:\copyfiles.bat", 2, 5)
The script waits until the batch file has finished or for 5 seconds, whichever comes first.
The exit function closes down Revolve.
exit()
The exitWindows function gracefully exits Revolve, any other open applications, and Windows.
exitWindows()
The expandComps function expands any databases which were compressed with the compressComps function.
expandComps(set)
To expand all COBOL databases:
scope:=all; expandComps(system_component_cobol);
The fclose function closes an open fileHandle. This should always be done when a fileHandle is open.
(0|1)fclose(fileHandle)
myHandle:=fopen("C:\test.txt");
fclose(myHandle);
The fieldtoVar function maps a field to its local variables within COBOL\PLI programs.
fieldToVar(element)
Set of variables relating to field.
To map selected map field to variables:
show fieldtoVar(selected);
The fileCopy function copies a file from the specified location to the specified destination location.
fileCopy (srcString, destString, mode)
| srcString | the full path and filename of the source file | ||||
| destString | the full path and filename of the destination file | ||||
| mode | the overwrite mode:
|
1 indicates success. Any other value indicates failure.
ret:=fileCopy ("c:\temp\srcfile.tmp", "d:\files\srcfile.tmp", 0)
ret:=fileCopy ("c:\temp\srcfile.tmp", "c:\temp\newfile.tmp", 1)
The fileDelete function deletes the specified file.
fileDelete(string)
| string | the full path and filename of the file to delete |
1 indicates success. Any other value indicates failure.
ret:=fileDelete("c:\files\tempfile.txt")
The fixDbTime function will bring out of date database times up to date.
fixDbTime()
The flushStrings function flushes or clears any strings which are locked in the memory.
flushStrings()
The fopen function opens a file and returns its handle for use in other functions.
fileHandle fopen(strFileName, (0|1|2))
You must supply a filename, and an open mode, which must be one of 0, 1 or 2.
| 0 | truncate the file if it exists (default) |
| 1 | append to the file if it exists |
| 2 | open an existing file as read-only |
myHandle:=fopen("C:\test.txt", 1);
The fprintf function writes formatted output to an open file handle.
(0|1) fprintf(fileHandle, buffer);
myHandle:=fopen("C:\test.txt", 0);
fprintf(myHandle, "This string goes to a file .");
fClose(myHandle);
The freadch function reads a specified number of characters from the specified file, and returns them in a string. Subsequent calls to the function will return the next x number of characters. If the number of characters requested is greater than the remaining length of the file, just the remaining characters will be returned. If the end of the file is reached and there are no more characters, the returned string will have 0 length. If the number of characters is not specified, the function will return the next 200 characters by default. A maximum of 250 characters can be read with each call to the function.
freadch (handle,[integer])
| handle | the handle to the currently open file (opened using the fopen mode 2) |
| integer | the optional integer specifying the number of characters to read. The maximum value is 250. Greater values will be reset to 250. If you do not specify an integer, the whole file or 250 characters will be read, whichever is the shorter. |
fileHandle:=fopen("c:\file.txt", 2)
newString:=freadch (fileHandle)
newString:=freadch (fileHandle, 20)
fClose(fileHandle)
The freadln function reads a line from a currently open text file and returns it in a string. The function is limited to 260 characters, so if the line you are reading exceeds this limit, it will be truncated. Subsequent calls to the function will return the next line in the file. When the end of the file is reached, the returned string will have 0 length.
freadln (handle)
| handle | the handle to the currently open file (opened using the fopen mode 2) |
fileHandle:=fopen("c:\file.txt", 2)
newString:=freadln (fileHandle)
fClose(fileHandle)
The funcPnt function accepts entities, components, or programs and returns the results of the Function Point Analysis for those elements.
funcPnt(program|component)
setFPA :=funcpnt(system_component_cobol="BATCH1");
show %25 "Type", %12 "Low", %12 "Medium", %12 "High";
show %25 "External Inputs", %12 setFPA[0], %12 setFPA[1],
%12 setFPA[2];
show %25 "External Outputs", %12 setFPA[3], %12 setFPA[4],
%12 setFPA[5];
show %25 "External Inquiries", %12 setFPA[6], %12 setFPA[7],
%12 setFPA[8];
show %25 "ILFs", %12 setFPA[9], %12 setFPA[10],
%12 setFPA[11];
show %25 "EIFs", %12 setFPA[12], %12 setFPA[13],
%12 setFPA[14];
show %25 "Unused", %12 setFPA[15];
The getClipboardText function returns the textual contents of the clipboard.
getClipboardText()
Copy some lines of code in the editor. Then type:
show getClipboardText();
The text is returned in the Shell.
The getClipboardUids function returns the UID's that have been copied to the clipboard.
getClipboardUids()
In the Programs Browser, right-click a program and select Capture Results. Select Copy to Clipboard and click Ok. Then type:
show getClipboardUids();
The program UID is displayed in the Shell tool.
The getDate function returns the current date.
getdate()
show getDate();
The getDateheading function returns the current date in a string.
getDateheading()
newString:=getDateheading()
gives you, for example: "Thursday, September 5, 2002"
The getEEProjectDir function returns the directory where worksheets, analysis tools, and sets for the current project are stored. If you are using a shared project, this will be the directory that the current user specified for their individual project settings to be saved.
getEEProjectDir()
show getEEProjectDir();
The getenv function retrieves an environment variable's value.
getenv(string)
String-value of environment variable
To retrieve an environment search path:
show getenv("PATH");
The getFileList function searches the specified directory, and subdirectories if specified, for filenames matching the specified pattern. The function returns a set of matching files as strings.
set getFileList (directory, pattern, [,(0|1)]);
To search the Revolve samples directory and its subdirectories for a list of the files whose filenames match the pattern "*.cbl":
getFileList("C:\product\samples\", "*.cbl", 1);
The getHighlights function returns a set of highlighted items based on the Highlighted color. For example, if you want to display all the source components that have been highlighted in red, specify red as the input parameter.
getHighlights(string)
show getHighlights("red");
The getInstallDir function returns the Revolve product installation directory.
getInstallDir()
show getInstallDir();
Gets or retrieves project options.
getOption(string);
show getOption("PostProcessingScript");
Returns a set of strings for the search paths of the specified component or project.
getPathSource([UID]);
show getPathSource(system_component_cobol[0])
The getProjectDir function returns the directory where the current project is stored.
getProjectDir()
show getProjectDir();
The getRelDest function returns a list of all TO entities that are used by user-defined relations.
getRelDest()
show getRelDest();
The getRelDestString function returns a list of TO strings that are used by user-defined relations.
getRelDestString()
show getRelDestString();
The getRelSrc function returns a list of all FROM entities used by user-defined relations.
getRelSrc()
show getRelSrc();
The getRelType function returns a list of all user-defined relations that exist in the database.
getRelType()
show GetRelType();
The getSearchExclusion function returns a list of search exclusions for the current project.
getSearchExclusion()
Set of strings
show getSearchExclusion();
The getTagType function returns the specified annotation's type.
getTagType(elemAnnotation)
public=3
private=2
annotation not found=0
Returns a set of text lines for the uid passed in.
getTextContent(uid)
Set of strings
show getTextContent(selected);
Returns a set of filenames that are being translated to a new filename.
getTransFrom()
Returns a set of filenames based on the translation.
getTransTo()
The getUsageValue function returns a set of values for the variable-named string at the location of the statement represented by the uid in the context of simulated execution.
getUsageValue(uid, string)
| uid | the uid of a COBOL statement that specifies a location in the program where you want to query the value of the interesting names. Different locations could lead to different values, even for the same string name. |
| string | the name of the variable whose value you want to query. |
To show the possible values contained in a working storage:
show getValue(var="WS-MAIN-MENU");
The getValue function takes a set of variables and returns a set of strings that represent values that could be contained in the variables.
getValue(set)
Set of strings
To show the possible values contained in a working storage:
show getValue(var="WS-MAIN-MENU");
The grep function scans system files for specified strings.
grep(strmatch, strfilename [, casesensitive(0|1)])
grep("WS-XCTL-PROGRAM",
"C:\product\SAMPLES\SAMPLEAPP\COBOL\ONLINE5.CBL", 1)
The function halstead accepts a program or component and returns the calculated Halstead metric.
halstead(program|component)
Set
show halstead(system_cobol_program="BATCH1");
The help function accesses the on-line help system to provide information about various topics.
help("topic")
help("shell"); help("source view"); help("sour"); The helpIndex function brings up the Help Index for Revolve.
helpIndex()
The highlight function enables you to highlight specified pieces of your source code in the specified color.
highlight(set [, string])
To highlight your stream files' source code in red
highlight(system_component_stream, "red");
To highlight your COBOL PERFORM statements in yellow
highlight (cobol_state_perform, "yellow");
The impactAdd function establishes the starting point for the specified impact analysis. This function is for interactive use with the Shell tool.
impactAdd(impact,set)
1=successful 0=error
To obtain the specified set of impacted elements from a COBOL variable:
scope :=all; vImpact :=impactNew(); impactAdd(vImpact, cobol_var="HDGI-DESC"); impactExpand(vImpact); show impactGetImpacted(vImpact,cobol_var="HDGI-DESC"); impactFree(vImpact);
The impactExpand function performs impact analysis expansion on the current set of starting points within the impact. This function is for interactive use with the Shell tool.
impactExpand(impact)
1=successful 0=error
To obtain the specified set of impacted elements from a COBOL variable:
scope :=all; vImpact :=impactNew(); impactAdd(vImpact, cobol_var="HDGI-DESC"); impactExpand(vImpact); show impactGetImpacted(impact,cobol_var="HDGI-DESC"); impactFree(vImpact);
The impactFree function frees the impact created by the impactNew function. This function is for interactive use with the Shell tool.
impactFree(impact)
1=successful 0=error
To obtain the specified set of impacted elements from a COBOL variable:
scope :=all; vImpact :=impactNew(); impactAdd(vImpact, cobol_var="HDGI-DESC"); impactExpand(vImpact); show impactGetImpacted(impact,cobol_var="HDGI-DESC"); impactFree(vImpact);
The impactGetChain function returns the traced chain of events that resulted in an identified impact. This function is for interactive use with the Shell tool.
impactGetChain(impact, set, set);
show impactGetChain(vImpact, vStart, vEnd);
The impactGetImpacted function returns the set of impacted elements from the specified set. This function is for interactive use with the Shell tool.
impactGetImpacted(impact, set)
Set of impact elements
To obtain the specified set of impacted elements from a COBOL variable:
scope :=all; vImpact :=impactNew(); impactAdd(vImpact, cobol_var="HDGI-DESC"); impactExpand(vImpact); show impactGetImpacted(impact,cobol_var="HDGI-DESC"); impactFree(vImpact);
The impactLoad function loads an impact object from a file saved with the impactSave function. This function is for interactive use with the Shell tool.
impactLoad(string)
Impact Object
vImpact:=impactNew();
impactAdd(vImpact, cobol_var="HDGI-DESC");
impactExpand(vImpact);
impactSave(vImpact, C:\impact.sav");
impactFree(vImpact);
vImpact2:=impactLoad("C:\impact.sav");
show impact Get Impacted(vImpacted, cobol_var="HDGI-DESC");
impactFree(vImpact2);
The impactNew function creates a new impact analysis object. This function is for interactive use with the Shell tool.
impactNew()
To obtain the specified set of impacted elements from a COBOL variable:
scope :=all; vImpact :=impactNew(); impactAdd(vImpact, cobol_var="HDGI-DESC"); impactExpand(vImpact); show impactGetImpacted(impact,cobol_var="HDGI-DESC"); impactFree(vImpact);
The impactSave function saves the impact analysis object to file. The file is available for later use and can be reloaded with the impactLoad function. This function is for interactive use with the Shell tool.
impactSave(impact,string)
Impact object
vImpact:=impactNew();
impactAdd(vImpact, cobol_var="HDGI-DESC");
impactExpand(vImpact);
impactSave(vImpact, C:\impact.sav");
impactFree(vImpact);
vImpact2:=impactLoad("C:\impact.sav")
show impact Get Impacted(vImpacted, cobol_var="HDGI-DESC");
impactFree(vImpact2);
The impactWalk function generates a list of variables that are impacted by the passed variable. This function is for interactive use with the Shell tool.
impactWalk(set[,level])
Set of impacted elements
To show impacts for a COBOL variable:
scope:=all; show impactWalk(cobol_var="ws-sales-read");
The impactWalkProgram generates a list of variables that are impacted within a specified program. This function is for interactive use with the Shell tool.
impactWalkProgram(set, synonymonly (1|0), [,level, [pruneflag,[limitflag]]])
| set | set of variables |
| synonymonly | boolean flag where 1=true and 0=false |
| level | impact trace level with default set to 300. |
| pruneflag | integervalue that corresponds to the Prune options in the
Impact Analysis tool. the integer value must be calculated from the following
defined constants:
SetOnPruneAll indicates that all Prune options are used. Subtract flag integers from 255 to select all options with exceptions. For example, 253 means all options are used except SetOnSupstedBuffer. |
| limitflag | integer value that corresponds to the Impact Through options
in the Impact Analysis tool. The integer value must be calculated from the
following defined constants:
SetOnLimitAll indicates that all Impact Through options are used. Subtract flag integers from 8191 to select all options with exceptions. For example, 4095 means all options are used except SetOnReference. |
Set of impacted variables
To show a list of variables that are impacted within a COBOL program:
scope:=all;
show impactWalk Program (cobol_var="ws-sales-read");
To set flags for Prune and Impact Through options:
scope:=all
show impactwalkprogram (cobol_var="was-sales-read",
1, 300, 6, 24);
SetOnSupstedBuffer=2 and SetOnCopybookBuffer=4
SetOnArith=8 and SetOnChildren=16
In this example only those 4 options are used in identifying impacts for the specified variable.
The informationBox function opens the Browser that corresponds to the specified element.
informationBox(element)
1=successful
0=error
To bring up a Browser for a data file:
scope:=all; informationBox(system_data_file="PROD.GAME.MASTER");
The integrate function initiates the system wide phase (phase 7) of the Parsing process.
integrate()
* In shareable projects this function is exclusive to the administrator.
The invoke function loads and executes a file of REQL commands known as a script.
invoke(filename)
1=successful 0=error
To run a REQL script that checks indentation:
invoke("c:\product\script\standard\indent.rqc");
The isAdmin function indicates that the user has administrator access to the project.
isAdmin()
1=successful 0=error
In Administrator mode:
if (isAdmin()) show "I am the administrator!";
The isShareable function indicates whether the project is sharable or single-user.
isShareable()
1=current project is shareable
0=current project is single-user
if (! isShareable()) show "Single-user project";
The function itoa accepts a number and returns the corresponding character value.
itoa(number)
String
strcurrentyear:=(itoa (1997)); show strcurrentyear;
The itou function accepts an integer and returns the corresponding UID representation.
itou(integer)
corresponding UID
vUid := itou(35209223)
The loadSetFromFile function returns the REQL set stored in the specified file.
loadSetFromFile(strfilename);
The lockUID function locks the annotation for modification through the addRel function. An annotation must be locked to in order to add or remove elements and descriptions. An error can occur if the annotation has been locked by another user.
lockUID(UID)
To create a new annotation and add a connected paragraph:
scope:=all;
vAnnotation:=addEntity("My Annotation",
type="user_annotation");
lockUID(vAnnotation);
addRel(vAnnotation, relation="hasa_user_connectedto",
cobol_label_para="END-FILE-BROWSE");
unlockUID(vAnnotation);
The logError function logs an error message to the Revolve error log file.
logError(string)
1=successful 0=error
To log an error message to the error log file (c:\Revolve.log):
logError ("This is an error!");
The make function checks the status of each component in the project. If any of the components have an updated status of anything other than "Loaded," then those components are parsed and/or loaded depending on their new status. This command is used to bring all components in the database up to date. Only available to the administrator.
make()
1=successful 0=error
make();
* In shareable projects this function is exclusive to the administrator.
The makeAdmin function puts the current database in Administrative mode. Administrative mode provides such Revolve functionality as parsing, adding/deleting components, and completing the project.
makeAdmin()
1=successful 0=error
if (!isAdmin()); makeAdmin();
The makeDir function creates the specified directory. The function works to one level deep, so will create a directory only if the parent directory exists i.e. to create a structure several layers deep, you need to make multiple calls to this function.
makeDir (string)
| string | the full path of the directory to create |
1 indicates success. Any other value indicates failure.
ret:=makeDir ("c:\tempdir")
The makeSelected function performs the make operation on the specified items in the scope.
makeSelected()
To perform a make on all COBOL programs:
scope:=all; scope:=system_component_cobol; makeselected();
* In shareable projects this function is exclusive to the administrator.
The makeShareable function creates a shadow project from the open project. This enables the project to be shared by many users.
makeShareable(strpath)
To make the open project shareable:
makeShareable("c:\projects\shared\");
The project is now shared and open in administrative mode.
The makeTagLocal function moves a public annotation to the private annotation directory.
makeTagLocal(elemAnnotation)
1=successful 0=error
/*see lockUID !to create an annotation*/ makeTagLocal(vAnnotation);
The makeUser function switches the operation of Revolve from Administrator to User. This function disables Revolve features that are reserved for the Administrator. The makeUser option is only available in the Administrator mode only.
makeUser()
1=successful 0=error
To change from Administrator to User:
if(isAdmin()) makeUser();
The mccabe function accepts a program or component and returns the calculated McCabe metric.
mccabe(program|component)
set
show mccabe(system_cobol_program="BATCH1");
The mcclure function accepts a program or component and returns the calculated McClure metric.
mcclure(program|component)
Set
show mcclure(system_cobol_program="BATCH1");
The mod function returns the remainder of the first number divided by the second.
mod(number1|number2)
iRem := mod(5,2)
iRem would equal 1.
The memWalk function is an internal debugging command. String signifies the file and directory where results will be stored. The numbers represent the level of debugging information that is displayed. The second parameter uses 0,1, and 2. 0 being the lowest level of information and 2 indicating the most. The third parameter should always be set to 0. After using the memWalk function go to the text file in the specified directory to view the results.
memWalk(string,number,number)
scope:=all;
memWalk("c:\test\temp1.txt",1,0);
The mult function performs integer multiplication. The syntax allows the multiplication of two numbers separated by a comma.
mult(number,number)
integer
show mult(5,6);
The offSetInto function returns the set of variables that are children of one of the specified variables and are the smallest to contain all the bytes at the specified offset.
offSetInto(set, location, size)
show red offSetInto(var="XDR-RECORD-LOAD",120,8);
The oneProgramImpact performs an impact analysis on the specified element through one program.
oneProgramImpact(element-for-Impact)
scope:=all; show oneProgramImpact(var="VB01-GAME-NO");
The open function opens the specified item.
open(string [, set])
open ("c:\programfiles\ie60\explorer.exe")
The overlay function returns sets of variables that overlay the specified variable.
overlay(set)
The parse function parses (or reparses) all components in the scope. After a parse, the command "show err" can be used to list the errors and warnings that were generated. A long parse can be stopped by clicking the stop icon on the status bar.
parse()
None
To parse all of the components in the project:
scope:=all; parse();
* In shareable projects this function is exclusive to the administrator.
The pause function invokes a Windows dialog box with the prompt and waits for the user to continue.
pause(string)
1=successful 0=error
To display the pause dialog box :
pause("Press ok to continue");
The postCommandAll function posts a REQL command to all users of Revolve. The parameter option "numDays" determines the expiration date for the command.
postCommandAll(string[,numDays])
Message-id of command
To say hello to everybody:
postCommandAll("open report;
show /"HELLO EVERYBODY/"");
* In shareable projects this function is exclusive to the administrator.
The postCommandProject function posts a REQL command to all users of current project.
postCommandProject(string [,numDays])
Message-id command
To say hello to project users:
postCommandProject("open report;
show /"Hello Project Users/";");
* In shareable projects this function is exclusive to the administrator.
The postMessageAll function posts a message to all Revolve users.
postMessageAll(string)
Message-id
postMessageAll("Hello World!");
The postMessageProject function posts a message to all users of the current project.
postMessageProject(string)
Message-id
postMessageProject("Hello Project Users!");
The postTag function moves a private annotation to public.
postTag(elemAnnotation)
1=successful 0=error
Function printf accepts a format string and a list of arguments and displays the formatted string converted to include the argument list.
printf(format string [, argument [,argument ...]] )
Similar to the "C" printf function, the format string may include specification characters which are used to translate the arguments in the argument list to the correct types for printing.
Each conversion specification begins with a "%" and is immediately followed by a conversion specification character.
| S | String of characters |
| D,I | Integer |
None
To display a sample string:
titlestr := "current year:"
currentyear := 1997
printf ("The %s is %d", titlestr, currentyear);
The processEntity function adds a system-wide object to the database with the name of the string and type passed. Links object to component, so that when the component is removed or reparsed the object will be destroyed. Optional uid parent specifies the system-wide parent of the object.
processEntity(string,type,component [,uidParent])
Newly created object
* In shareable projects this function is exclusive to the administrator.
The processRel function adds a system-wide relation between elemfrom and elements which will be removed if either object is removed (through reparse/component delete).
processRel(elemFrom,relation,elemTo|string|number)
1=successful 0=error
* In shareable projects this function is exclusive to the administrator.
The programCalls function enables you to examine calls between programs.
programCalls(program,numPrint,strSpacing);
The projectClose function closes the open Revolve project.
projectClose()
1=successful 0=error
To open a project, perform a make, and close:
projectOpen(C:\PRODUCT\REDB\SAMPLE.PRJ.");
make();
projectClose();
The REQL function projectDelete(0|1|2) enables you to delete areas of the current project. A parameter value of zero displays the same prompt as if this option were chosen from the Project menu. A value of 1 deletes the project files, but leaves the component databases. A value of 2 deletes both the project files and component databases.
projectDelete(0|1|2);
* In shareable projects this function is exclusive to the administrator.
The projectNew function creates a new project using the specified path and name.
projectNew(string)
1=successful 0=error
projectNew("C:\DATABASE\SAMPLE.PRJ");
The projectOpen function opens the specified project.
projectOpen(string)
1=successful 0=error
To open a project, perform a make, and close:
projectOpen(C:\PRODUCT\REDB\SAMPLE.PRJ.");
make();
projectClose();
The projectSync function enables you to load specified files from a specified directory into the open project.
projectSync(strpath,strFileSpec,1|0 [type='system_component_text'])
| strpath | path to the directory that contains the files you want to add to the open project |
| strfilespec | names or name patterns of the files you want to add to the open project |
| 0 | do not recurse subdirectories |
| 1 | recurse subdirectories |
| type | Revolve type [optional] |
show projectSync ("C:\project\database", "*.cbl")
The prompt function displays the specified prompt and assigns the user variable with the results.
prompt("prompt", user_variable)
Number
If "OK" is chosen, 1 is returned
If "CANCEL" is chosen, 0 is returned
To prompt for a drive specification:
prompt("Enter Drive:",vDrive);
The punctuateInteger function returns a string containing the punctuated version of the provided integer. The punctuation is determined from the locale settings of the machine generating the reports. Decimal places are not reported.
punctuateInteger(integer)
| integer | the integer to be punctuated |
newString:=punctuateInteger(1234567)
gives you 1,234,567, assuming UK/ US locale settings.
The rebuildRl function reconstructs the label index.
rebuildRl()
rebuildRl();
* In shareable projects this function is exclusive to the administrator.
The rebuildRt function reconstructs the literal index.
rebuildRt()
rebuildRt();
* In shareable projects this function is exclusive to the administrator.
The rebuildRv reconstructs the variable index.
rebuildRv()
rebuildRv();
* In shareable projects this function is exclusive to the administrator.
The register function.
register(dllName, entryPointName,reqlName,strParams,strReturn)
The reintegrate function is used to reintegrate databases of the components in scope.
reintegrate()
reintegrate();
* In shareable projects this function is exclusive to the administrator.
The removeComps function removes specified components from the project.
removeComps(setComp [,0|1 [,0|1]])
| 0 | do not delete the component database |
| 1 | delete the component database |
| 0 | do not remove the component search directories |
| 1 | remove the component search directories if present |
To remove JCL components from your project:
scope:=all
removeComps(system_component_jcl, 1, 1);
* In shareable projects this function is exclusive to the administrator.
The removeMessage function removes a message from the messaging system.
removeMessage(messageID)
1=successful 0=error
To post a temporary message during processing:
vMessage:=postMessageProject("Processing...");
removeMessage(vMessage);
The removePathSource function is complementary to addPathSource. The latter adds a search directory to either the project or component, and removePathSource removes a search path from either a component or project.
removePathSource(string, [type, -uidComp]])
To remove a search path for COBOL components:
removePathSource("c:\sample\cobol\",
type="system_component_cobol");
* In shareable projects this function is exclusive to the administrator.
The removeSearchExclusion function removes an entry from the search exclusion list.
removeSearchExclusion(index)
1=successful 0=error
removeSearchExclusion(0);
* In shareable projects this function is exclusive to the administrator.
The replaceChars function replaces all occurrences of a string within the source string with the provided replacement string. For example, you can replace all occurrences of the & character in a string with the % character. The returned string is limited to 1000 characters, so if the result of the replacement exceeds this, it will be truncated.
replaceChars(srcString, oldChars, newChars)
| srcString | the original source string |
| oldChars | the string to be replaced |
| newChars | the replacement string |
newString:=replaceChars("ACCT.CBL", "C", "B")
converts the string to ABBT.BBL
newString:=replaceChars("ACCT.CBL", "CC", "F")
converts the string to AFT.CBL
newString:=replaceChars("ACCT.CBL", "ACCT", "ABCDEFG")
converts the string to ABCDEFG.CBL
The reqlFunctions function enables you to view a list of available functions and their syntax.
reqlFunctions()
To list existing REQL functions:
show reqlFunctions()
To show the syntax for the removeComps REQL function:
show reqlfunctions("removeComps");
The reqlScriptProperties function enables you to return the properties that have been defined for a REQL script. REQL script properties are defined with scriptProperty parameters.
reqlScriptProperties(strFileName [, string])
show reqlScriptProperties("c:\analyst\script\deptool.rqc",
"title");
The reqlVars function displays a list of REQL variables.
reqlVars([string])
show reqlVars();
The return function returns the flow of control from a REQL script.
return()
None
To return at the end of a script:
return();
Writes the contents of a REQL set to the specified filename. The set can then be reloaded with the loadSetFromFile function
saveSetToFile(set, strFileName);
The scopeUID function sets the scope as a specified annotation so the relations that are added will be added to that annotation.
scopeUid(UID)
To add element description to annotation element:
vAnnotation:=addEntity("My Annotation",
type="user-annotation");
Lockuid(vAnnotation);
Scopeuid(vAnnotation);
addRelation(vAnnotation, relation="hasa_user_connectedTo",
cobol_label_para="READ-FILE-MAIL-EXIT");
addRelation(cobol_label_para="dr",
relation="attr_user_description", "Element Description.");
unlockuid(vAnnotation);
The segregate function segregates system-wide database information for all loaded items in scope.
segregate()
1=successful 0=error
* In shareable projects this function is exclusive to the administrator.
The setClipboardText function enables you to place specified text on the local clipboard. The string you specify is copied onto the local clipboard and accessible from other tools.
setClipboardText(string)
setClipboardText("USERID=JFO");
The setClipboardUids function places specified UID's on the local clipboard. This UID can be passed into a Browser that accepts the specified UID.
setClipboardUids(set);
setClipboardUids(system_component_cobol);
Then open the Programs Browser and click Paste from clipboard. The programs are loaded into the browser.
The SetFind option determines if the specified element is within the specified set.
setFind(set,element)
If a non-negative number is returned, the element has been found in the set at the specified index.
scope:=all; vSetVars:=cobol_var; showVsetVars;
Select an element by right-clicking on it with the mouse and choosing Select from the speed menu. Its name appears at the bottom of the Shell tool and the Desktop.
show setFind(vSetVars, selected);
The setInteractiveMode function turns interactive mode on/off. When interactive mode is off the user is not prompted with confirmation message boxes.
setInteractiveMode(0|1)
1=successful 0=error
show setInteractiveMode(1);
The setOption function sets the specified strOption to the specified value or turns the option on/off. The following options are available:
setOption(strOption,1|0 or string-value)
| EnableACL | Turns the Automatic Component Locator on/off. |
| ConfirmACL | Prompts the user for confirmation of located components. |
| PublicAnnotation Dir | Sets paths for public annotations. |
| PostProcessingScript | Sets the name of the REQL script to be used for post processing. |
1=successful 0=error
setOption("EnableACL", 0);
setOption("PublicAnnotationDir","c:\");
* In shareable projects this function is exclusive to the administrator.
The setOutputToFile function sets the current output functions to the file. This lets you use show and printf, and have the output redirected to a file as opposed to the shell window.
(0|1)setOutputToFile(fileHandle)
myHandle:=fopen("C:\test.txt");
setOutputToFile(myHandle);
show components;
setOutputToShell();
fclose(myHandle);
The setOutputToShell function sets the current output functions to the shell. This should always be done after you set the output to a file, or no output can be seen.
(0|1)setOutputToShell(fileHandle)
myHandle:=fopen("C:\test.txt");
setOutputToFile(myHandle);
show components;
setOutputToShell();
fclose(myHandle);
The shellClear function clears the shell of previous activities.
shellClear();
shellClear();
The shellClose function closes the open shell.
shellClose();
shellClose();
The shellLoadFromFile function loads the specified text file into the current shell or report.
shellLoadFromFile(strFileName)
1=successful 0=error
open report;
scope:=all;
show cobol_var="*DATE*";
shellSaveToFile("c:\output.txt");
close report;
//new report//
open report;
shellLoadFromFile("c:\outout.txt");
shellprint();
The shellPrint function displays a Print dialog.
shellPrint()
1=successful 0=error
The shellSaveToFile function saves current report or shell to the text file specified in the strFileName parameter.
shellSaveToFile(strFileName)
1=successful 0=error
The shellSetTitle function gives the current report or shell the title that is specified in the string parameter.
shellSetTitle(string)
open report;
shellSetTitle("DATE IMPACT REPORT");
The sort function allows sorting of elements by specified attribute.
sort(string)
show sort(vSrt <:component by vSrt:>attr_reql_name);
Function split uses a single-byte delimiter to split text onto separate lines.
split(string, delimiter)
show split("the quick brown fox"," ")
returns
the quick brown fox
and
show split("DSN=ADV3DX.DXFORT.DEPSUSP.C0413A",".")
returns
DSN=ADV3DX DXFORT DEPSUSP C0413A
This can also take the place of the functions WORD() and WORDS(), as in the examples below:
show count(split("the quick brown fox"," "))
returns "4", which is the number of words in the sentence.
show split("the quick brown fox"," ")[2]
returns "brown".
Function sprintf writes formatted output to a string.
sprintf(strFormat[,argument...])
strvar:=sprintf
show sprintf("%I %S", 3456, "Fred");
The status function performs status updates on all components in the loaded project.
status()
status();
* In shareable projects this function is exclusive to the administrator.
The strcase function takes a string and returns it converted into upper or lower case.
strcase(string, 0|1)
| string | the string to convert |
| 1 | lower case |
| 0 | upper case |
newString:=strcase("aCcT01.cBl", 0)
converts the string to ACCT01.CBL
newString:=strcase("aCcT01.cBl", 1)
converts the string to acct01.cbl
Function strconcat accepts two strings or variables containing strings and returns a string with the second concatenated onto the end of the first.
strconcat(string,string)
string
firstname := "John"; fullname := strconcat(firstname,"Doe"); show fullname;
Function strcopy copies the specified string to the specified variable.
strcopy(variable,string)
strcopy returns dest.
newvar:=""; strcopy(newvar, "John");
Function strlen accepts one string and returns a number representing the length of the string.
strlen(string)
Number
To assign the length of a path to a variable:
namelength:=strlen("c:\product\bin\Revolve.exe");
The strscan function returns index of string2 specified within string1.
strscan(string1,string2)
show strscan("cats and dogs", "dogs");
The substr function takes a string and returns a substring. First is the number of the first character in the substring and length is its length. The first character in the string has the character location 0. If length is equal to 1, substr returns a single character. The substring is truncated if first+length is greater than the length of the string.
substr(string, first, length)
String
To show the first four characters of the name of the selected element:
show substr(selected:>attr_name, 0, 4);
To show the second character of the selected element:
show substr(selected:>attr_name, 1, 1);
The sum function returns the sum of the set of integers.
sum(set)
Number
To show the total:
show "The total of the set is ",sum((5&3)); 8
To show the number of lines in a component:
show "The total of number of lines is ",
sum(component:>lines);
The tableAddRecord function adds data to a row in a table that has been created with the tableDeclare function. The contents of the record are specified with this function
tableAddRecord(table,...)
| table | name given to the table |
| ... | data contained in table |
To insert data at the 0 level of the table named vTab1:
show TableAddRecord(vTab1, 20,21,22, "Todd" );
The tableDeclare function creates a table based on a defined set or schema that you have created.
tableDeclare(set)
To create a schema to use in a table:
vSchema := []; vSchema := (vSchema & "YLoc:integer"); vSchema := (vSchema & "IndUsage:integer"); vSchema := (vSchema & "IndexNext:integer"); vSchema := (vSchema & "Name:string");
To incorporate vSchema into a table named vTab1:
vTab1 := tableDeclare(vSchema);
The tableDeleteRecord function deletes the specified row from a table.
tableDeleteRecord(table,index)
To delete the record stored in the 1 postion of table vTab1:
show tableDeleteRecord(vTab1, 1);
The tableInsertRecord function inserts a row into a table.
tableInsertRecord(table,index,...)
To insert a row into table vTab1:
show tableInsertRecord(vTab1, 5, 1000, 2000, 3000,
"Inserted Data 1");
The tableNumColumns function returns the number of columns in a table.
tableNumColumns(table)
To return the number of columns in table vTab1:
show tableNumColumns(vTab1);
The tableNumRows function returns the number of rows in a table.
tableNumRows(table)
To return the number of rows in table vTab1:
show tableNumRows(vTab1);
The tableSchema function retrieves the schema for the specified table.
tableSchema(table)
To retrieve the schema used in table vTab1:
show tableSchema(vTab1);
The tableSort function enables you to sort a table based on a set in ascending and descending order.
tablesort(table, set [,0|1])
| 1 | descending |
| 0 | ascending (default) |
To sort table vTab1 in descending order based on the column assigned to vSortFields:
show tableSort(vTab1, vSortFields, 1);
To sort the same field in ascending order:
show tableSort(vTab1, vSortFields, 0);
The tableUpdateRecordField updates a table field with new data.
tableUpdateRecordField(table,index,strField,value)
To change the name field from "Input/Output" to "I/O":
show tableUpdateRecordField(vTab1, 0, "Name", "I/O");
The timer function displays the current time down to hundreths of a second, as well as the elapsed time since the previous timer call.
timer()
show timer(); vcount:=count(COBOL_STATE); show timer();
For information on this function refer to the timerUpdate function.
The timerUpdate function initiates and establishes parameters for a progress bar. The first time this function is called, a new progress bar will be invoked. All subsequent calls will update the parameters and the status will be displayed as a progress bar. The "title" string specifies the title of the window. The status string designates the component that is being processed. The i specifies the current position of the progress bar where n indicates the maximum number of position. In order to close a progress there must be a call to timerKill.
timerUpdate("title", "status string", i
# of current, n # of total steps)
scope :=all;
vCount:=0
vTotal:=count(component_cobol);
for vComp<: component_cobol{
vProgramName :=vComp:.attr_reql_name;
timerUpdate("Example Process Monitor",
vProgramName, vCount, vTotal);
-------------------
There will be a process for each COBOL program.
-------------------
}
timerKill();
The translate command adds the specified import translation to the current project.
translate "from" "to"
scope :=all; translate "test" "testing"
* In shareable projects this function is exclusive to the administrator.
The tree function shows hasa tree relations for the specified UID.
tree(uid [, relation])
show tree(system_component_cobol);
The trim function trims a string value of spaces before and after.
trim(string, [0|1|2])
| 0 | trim spaces both before and after |
| 1 | trim spaces before only |
| 2 | trim spaces after only |
The uniquify function removes duplicated elements from the specified set.
uniquify(set)
Set
To uniquify a set of names which contains strings:
names:=uniquify(names);
The unlockUID function unlocks an annotation following an update.
unlockUID(annotation UID)
To create a new annotation and unlock it for use.
scope:=all;
vAnnotation:=addEntity("My Annotation,
type="user_annotation");
lockUID(vAnnotation);
addRel(vAnnotation, relation="hasa_user_connectedto",
cobol_label_para="END-FILE-BROWSE");
unlockUID(vAnnotation);
The unused function takes a set of labels or statements and returns the subset which is never used.
unused(set)
Set of labels or statements
To show the CICS statements which are never used:
show yellow unused(cics_state);
The updateshared function updates the shareable database from a shadow project.
updateShared()
1=successful 0=error
makeAdmin(); updateshared();
* In shareable projects this function is exclusive to the administrator.
The varToField function maps a set of variables to related BMS/MFS fields.
varToField(set)
Set of elements.
scope:=all; show varToField(cobol_var="HBVRIFY-USER-NO-I");
Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.