Environment

Home	Starting	Environment	DBMS	VisualPQL	Procedures	SQL	Forms	Host/API	Index

Environment

Commands

Virtually all SIR/XS features can be run either from menus or from commands. A single command can be entered through the DBMS Command menu item but normally commands are run as scripts or procedures. There are a specific set of commands that can be used when creating procedures. These commands can be anywhere in the input set and can be used to:

Include comments and remarks.
Modify the input text. As input is read, it can be modified by:
- Global variable substitution.
  Global variables are named variables that have a value, primarily used for text substitution. If input text includes the name of the global variable enclosed in angle brackets < >, the current value of the global variable is substituted into the text. Globals can be defined and assigned values with the GLOBAL and GCOMPUTE commands. There is also a set of predefined system globals that can be used for such things as today's date.
- Parameter substitution.
  Parameters can be specified when initiating a command stream and these can be used by the commands to set particular values.
- Text inclusion.
  The INCLUDE commands include text from a buffer, file or member at the point of the command. Text inclusion commands can appear within any input source including included text. The FINISH and PEND commands terminates processing of the current input source. PEND returns to the next higher level input source to resume execution. FINISH returns to the menus or ends a batch run.
- Text generation and repetition.
  Repetitive code can be generated with the DO REPEAT command. This takes a block of text and expands it. When the entire block has been expanded, the command processor begins processing the commands in the expanded block.
Control command processing.
Commands can be processed conditionally either through the block structured CIF (for Compile IF) command or by the logical tests that can skip to specified places in an input procedure. These control which commands are processed.
CIF sets conditions that either initiate or suspend processing of subsequent commands. When processing is suspended, commands are skipped until another CIF command halts skipping. The CIF TRUE & FALSE and CIF END subcommands allow conditional processing within a CIF.
Control output. Commands that control output and other settings include:

Comments and Remarks

Any text after a vertical bar (from that point to the physical end of the input line) is treated as comments. Command continuation lines are not affected by comments after a vertical bar. i.e. as long as the comment is at the end of the line, the command can be continued on a subsequent line.

The comment command can also be used.

COMMENT text

Inserts comment text. This is printed in the output listing. This is a command and therefore cannot appear between continuation lines for another command. The comment can have continuation lines.

REMARK 'text'

Writes a remark to the output file.

The printing of remarks and comments is controlled by PRINT BACK settings.

Global Variables

Global variables are named variables that have a value. These variables are global in the sense that they are stored in the environment externally to any specific routine. Global variables are primarily used for text substitution but also provide an easy and convenient method of passing small amounts of information between menus and programs.

Global variables have standard SIR/XS names.

Globals can be defined and assigned values in four ways:

with the GLOBAL command
with the GCOMPUTE command
with the Globals option on the Settings Menu.
In VisualPQL programs with the GLOBALN and GLOBALS functions

If input text includes the name of the global variable enclosed in angle brackets < >, the current value of the global variable is substituted into the text. For example, suppose a global variable called RECNAME has the value PARTS assigned to it. If the following line is input:

PROCESS REC <RECNAME>

The value of the global variable RECNAME is substituted into this line before the VisualPQL compiler deals with it. The line that the compiler works with is:

PROCESS REC PARTS

Whenever a global variable is found in the input text enclosed in angle brackets, the current value of the variable is substituted in the text. This substitution happens at input time. If the program is compiled at one time and then run at some later time, the value of the global variable at run time is irrelevant.

Because the system employs a "read ahead" strategy to discover whether the next line is a continuation of the previous line, the value of the global variable is NOT available on the first line after the command that creates (or updates) the variable. For example:

PROGRAM
GLOBAL GREET = Hello World
WRITE <GREET>
END PROGRAM

This example does not write "Hello World" because the global variable was not set when the line WRITE <GREET> was read. Use the following:

GLOBAL GREET = Hello World
C    blank line for global setting
WRITE <GREET>

This example writes the greeting. Place a blank comment line after the global assignment to use the value immediately in the next subsequent command.

Global variables at run time

The value in a global variable can be tested in a program at run time by referencing it in a function. There are two VisualPQL functions NGLOBAL and SGLOBAL that read the run time value of a global variable; the GLOBALN and GLOBALS functions update the current value of a global variable. The S and N prefix/suffix refer to string variables or numeric variables. These functions happen at run time.

These functions can be used to pass parameters between two compiled programs; between a compiled program and a text procedure; between a text procedure and a compiled program; etc. The value can be used outside a program at compile time for straightforward text substitution and can be referenced inCIFand DO REPEAT commands.

GLOBAL

GLOBAL global_name = value [, global_name = value] ...

The GLOBAL command creates global variables and assigns values. Multiple global variables can be defined on a single GLOBAL command, in which case use a comma as the delimiter between global variable specifications.

The value of a global is held internally as text. By default, leading and trailing blanks are deleted. Leading and trailing blanks as well as commas can be specified by delimiting the value with the dollar sign ($), single or double quotes or open/close parentheses () and these delimiters are stripped out of the text. For example:

GLOBAL DATEGLOB = $   Jan 24, 2006$

If you need to include a delimiting quote or dollar as part of the parameter, specify the character twice e.g.

MONEY is A$41,500:

GLOBAL MONEY = $A$$41,500$

alternatively use:

GLOBAL MONEY = 'A$41,500'

GCOMPUTE

GCOMPUTE global_varname = expression

Initialises a new global variable if it does not already exist or recalculates the value of the variable if it already exists.

The expression may contain:

string constants ( quoted strings )
string operators ( + )
numeric constants
numeric operators ( + , - , / , * , ** )
parentheses
global variable names

Note: GCOMPUTE differs from GLOBAL in that it evaluates the expression and may substitute values for globals in the expression. The GLOBAL command treats the value as literal text and does no evaluation.

System Globals

As well as global variables defined by the user there is also a set of system globals. The system global variables are:

CBLEVEL: The count of the number of times that the data dictionary of the current database has been updated.
CPTIME: The elapsed time in milliseconds since the beginning of the session.

Parameter Substitution

Parameter substitution is similar to global variable text substitution but works with positional specifications rather than named variables.

Specify the parameter to be substituted in the text as a number inside angle brackets, such as <1> or <2>. When the set of text is RUN, supply the parameters to substitute as a list of values. The numbers specified on the text refer to the position of the parameter on the input list. Thus <1> refers to the first parameter, <2> the second and so on. The same number can be used multiple times in the input text if the same value is to be substituted. Separate each entry in the list with commas and enclose the whole list in parentheses. For example, suppose the following program:

RETRIEVAL
.  PROCESS REC <1>
.  WRITE <2>
.  END REC
END RETRIEVAL

This might be run with a parameter list such as:

(PARTS , PARTNUM PARTNAME PARTCOST)

The two parameters are separated by the comma. After text substitution has been performed, the program is:

RETRIEVAL
.  PROCESS REC PARTS
.  WRITE PARTNUM PARTNAME PARTCOST
.  END REC
END RETRIEVAL

Run time parameters can be specified:

On the RUN command
At the Args string when using the Run option from the member dialog.
On INCLUDE commands.

Just as with global variables, text parameter substitution happens at compile time. The NARG and SARG functions return the numeric or string parameters at run time.

INCLUDE BUFFER | FILE | MEMBER

INCLUDE BUFFER "buffer_name"          [ (parameter_list) ]
INCLUDE FILE { filename | attribute } [ (parameter_list) ]
INCLUDE MEMBER member                 [ (parameter_list) ]

Synonyms:

SET BUFFER "buffer_name"          [ (parameter_list) ]
SET FILE { filename | attribute } [ (parameter_list) ]
CALL member                       [ (parameter_list) ]

The INCLUDE commands include text from a buffer, file or member at the point of the command. Text inclusion commands can appear within any input source including included text.

Positional parameters specified on the INCLUDE applies only to the commands directly included by that command. If there are further text inclusion commands within an included set of text, then parameter numbers are reset. When a level is returned to from a deeper level, the calling parameters are once again in effect. The INCLUDE BUFFER command includes the text of the specified edit buffer at the point of the command. SET BUFFER is a synonym for INCLUDE BUFFER. Buffer names obey normal SIR/XS rules.

The INCLUDE FILE command includes the text of the specified file at the point of the command. SET INPUT is a synonym for INCLUDE FILE.

Specify a full filename or attribute.

The INCLUDE MEMBER command includes the text of the specified file at the point of the command. CALL is a synonym for INCLUDE MEMBER. Specify the member to include. Only text members (with the :T suffix) can be referenced. Use INCLUDE MEMBER * in batch runs or at the front of a command set, to pass parameters to the commands that follow.

Specify a parameter list where required. Enclose the whole list in parentheses, separating individual parameters with commas. Note that blanks do not separate parameters. The parameters can be delimited if required. The delimiters are quotes (single/double), open/close parens () and dollar signs. Note that a start/end dollar or open/close parentheses are stripped out while the quotes are passed down as part of the parameter. Parameters are strings and maintain their upper/lower case regardless as to delimiters. The only character that is significant to the command is comma so, if you need to pass a comma as part of the parameter, you must delimit the parameter, but avoid accidentally starting your parameter with a delimiter. If you need to include a delimiting quote or dollar as part of the parameter, specify the character twice.

Examples:

INCLUDE FILE 'C:\PROGS\WEEKLY.PQL'
INCLUDE FILE WAREHOUS.PQL (PARTS, PARTNUM PARTNAM PARTCOST)
INCLUDE BUFFER "Test Program"
INCLUDE BUFFER PARTS ( PARTS, PARTNUM PARTNAM PARTCOST)
INCLUDE MEMBER REPORTS.WEEKLY
CALL REPORTS.WEEKLY
CALL REPORTS.WAREHOUS ( PARTS, PARTNUM PARTNAM PARTCOST)

Assume a program, TEST1 is called. Any positional parameters in that program are referred to as <1>, <2>, etc. If this now calls a second program, TEST2, it also refers to any positional parameters as <1>, <2>. In the example, in TEST1, the positional parameter <1> is replaced with a "a"; in TEST2, the positional parameter <1> is replaced with a "c". For example:

INCLUDE MEMBER TEST1 (a,b)

TEST1:T
WRITE <1>
INCLUDE MEMBER TEST2 (c,d)

TEST2:T
WRITE <1>

FINISH

FINISH

Terminates processing of all input source commands and returns control to the current environment i.e. the operating system for batch runs or the menus.

If FINISH occurs in a set of either VisualPQL or Record Schema commands, the following actions are taken:

Within a ViusalPQL program, FINISH generates an END PROGRAM or END RETRIEVAL command, then executes the compiled VisualPQL program. At the end of VisualPQL execution, control is returned to the executing process, skipping any other commands in the input source(s).
Within a Record Schema command set (either RECORD SCHEMA or MODIFY SCHEMA), FINISH generates an END SCHEMA, then executes the schema definition. After the schema has been executed, control is returned to the executing process, skipping any other commands in the input source(s)

PEND

PEND

Terminates processing of commands in the input source where it appears and resumes execution in the calling input source. Execution resumes with the command immediately following the CALL or INCLUDE that initiated the processing of the procedure containing the PEND. If PEND is executed in the highest level input source, it is equivalent to FINISH.

If PEND is executed within either a VisualPQL or Record Schema definition, the following actions are taken:

Within a VisualPQL program, PEND generates an END PROGRAM or END RETRIEVAL command, then executes the compiled VisualPQL program. At the end of VisualPQL execution, control is returned to the calling level.
Within a Record Schema command set (either RECORD SCHEMA or MODIFY SCHEMA), PEND generates an END SCHEMA, then executes the schema definition. After the schema has been executed, control is returned to the calling process.

DO REPEAT

DO REPEAT repeat_symbol = parameter_list [ / ... ]
.
.  commands to be repeated with symbol value replacement
.
END REPEAT

The DO REPEAT command defines a block of text, usually commands, that is repeatedly copied as input. For each copy of the commands, substitution parameters are inserted into the block. For example, if a DO REPEAT contains ten lines of code and is repeated ten times, one hundred lines of code are generated.

Note:
This command is not an alternative to one of the VisualPQL execution time commands such as the FOR command as it generates source code rather than looping at execution time.

A DO REPEAT block cannot be specified in another DO REPEAT.

The repeat symbol is a SIR/XS name. The parameter list is composed of one or more parameters. Delimit parameters from each other with blanks or commas. The text within the DO REPEAT block is repeated once for each parameter in the list. The value of the parameter is substituted where the repeat symbol is found within the text. By default, the text of parameters is taken to be a SIR/XS name.

For example:

DO REPEAT REPSYMB = employee, occup, review
ADD RECS FILENAME="REPSYMB.dat" /RECTYPE=REPSYMB
END REPEAT

The above text is expanded to be:

ADD RECS FILENAME="EMPLOYEE.dat" /RECTYPE=EMPLOYEE
ADD RECS FILENAME="OCCUP.dat" /RECTYPE=OCCUP
ADD RECS FILENAME="REVIEW.dat" /RECTYPE=REVIEW

To specify parameter values that are not SIR/XS names (whether standard names mapped to uppercase or non-standard names enclosed in curly brackets), delimit the parameter with quotes (single or double), the dollar sign ($) or opening/closing parentheses. Delimited parameters can be of arbitrary length (greater than 32 characters) and contain any characters. If you need to include a delimiting quote or dollar as part of the parameter, specify the character twice. Delimiters are stripped out of the text. For example:

DO REPEAT REPSYMB = $employee$, $occup$, $review$
ADD RECS FILENAME="REPSYMB.dat" /RECTYPE=REPSYMB
END REPEAT

The above code is expanded to be:

ADD RECS FILENAME="employee.dat" /RECTYPE=employee
ADD RECS FILENAME="occup.dat" /RECTYPE=occup
ADD RECS FILENAME="review.dat" /RECTYPE=review

Note. If you happen to have a SIR/XS name that starts with a dollar sign, then you must delimit this name

TO Keyword

Parameter values can be specified with the TO keyword. When the parameter values end in numbers and the parameter to the left of the TO has a number of lower value than the parameter on the right, the list includes all the numbers implied in the range. This also applies to special names wrapped in curly brackets ({Like This 01}). For example:

DO REPEAT X = REC1 TO REC5
WRITE SCHEMA FILENAME="X.sch" RECTYPE=X
END REPEAT

The above program is expanded to be:

WRITE SCHEMA FILENAME="REC1.sch" RECTYPE=REC1
WRITE SCHEMA FILENAME="REC2.sch" RECTYPE=REC2
WRITE SCHEMA FILENAME="REC3.sch" RECTYPE=REC3
WRITE SCHEMA FILENAME="REC4.sch" RECTYPE=REC4
WRITE SCHEMA FILENAME="REC5.sch" RECTYPE=REC5

Parameters cannot have embedded numbers. The non-numeric part must be the same. For example the following are both invalid parameters:

DO REPEAT x = X12P1 to X12P2
DO REPEAT  x = X1 to Y3

Numeric constants can be used as parameters. For example:

DO REPEAT X = 1 TO 3
REMARK "X"
END REPEAT

The above program is expanded to be:

REMARK "1"
REMARK "2"
REMARK "3"

Leading zeros can be specified in numeric parameters using $ (dollar sign) to delimit values. Note that the width of the number will be the width of the first parameter in the TO range. The dollar delimiters must be specified on both ends:

DO REPEAT X = $01$ TO $23$

Concatenation

DO REPEAT can be used to construct names by appending the text of the parameter to other text by specifying the repeat symbol preceded, or followed by an exclamation mark (!). For example, if the results of multiple tests are in variables called MATH1 TO MATH5, READ1 TO READ5 and AVG1 TO AVG5:

.  DO REPEAT X = 1 TO 5
.  WRITE 'Test Number X Scores: ' MATH!X READ!X AVG!X
.  END REPEAT

The repeat block expands to:

WRITE 'Test Number 1 Scores: ' MATH1 READ1 AVG1
WRITE 'Test Number 2 Scores: ' MATH2 READ2 AVG2
WRITE 'Test Number 3 Scores: ' MATH3 READ3 AVG3
WRITE 'Test Number 4 Scores: ' MATH4 READ4 AVG4
WRITE 'Test Number 5 Scores: ' MATH5 READ5 AVG5

Multiple Repeat Symbols

Multiple repeat symbols, each with its own parameter list can be specified. These specifications are delimited from each other with a slash (/). The lists should be of equal length and a warning is issued if they are not. When multiple repeat symbols are specified, the DO REPEAT block is repeated once for every parameter in the longest parameter list, substituting the next parameter from each list in turn. When unequal length lists exist, the parameters of the shorter lists are cycled as often as is necessary to exhaust the longest list. The same result of the previous example can be achieved with the following code.

DO REPEAT X = 1 TO 5/  M = MATH1 TO MATH5/
          R = READ1 TO READ5/
          A = AVG1  TO AVG5
.  WRITE 'Test Number X Scores: ' M R A
END REPEAT

Other Examples

DO REPEAT is useful anytime a set of similar code must be generated repeatedly. Any command can appear within a DO REPEAT block except for another DO REPEAT command.

Example 1. The following generates three different retrievals, each creating an SPSS file for the data in a different record type. Note that the repeat symbol RTNUM is used on the PROCESS REC statement and in the filename for the SPSS procedure command.

DO REPEAT RTNUM = 1 2 4
RETRIEVAL
.  PROCESS CASES
.    PROCESS REC RTNUM
.    GET VARS ALL
.    PERFORM PROCS
.    END REC
.  END CASE
SPSS SAVE FILE FILENAME = 'SPSS!RTNUM.SYS'
END RETRIEVAL
END REPEAT

Example 2. Consider a typical schema modification task in which many record types have the same variable with value labels. The following generates the value labels for a variable called MEDICINE in ten different record types:

DO REPEAT RTNUM = 1,4,7,8,9,13,14,15,20,22
MODIFY SCHEMA RTNUM
VALUE LABELS MEDICINE (1) 'Aspirin'       (2) 'Cough Syrup'
                      (3) 'Antihistamine' (4) 'Ointment'
END SCHEMA
END REPEAT

Example 3. Consider an application where many data files are created that have to be entered into the database with the ADD REC batch data input utility. The following set of commands reads in data from 27 files and writes out rejected records for each record type to a separate file:

DO REPEAT FILENUM = 1 TO 27
ADD REC INPUT = DATA!FILENUM.DAT
        ERRFILE = ERR!FILENUM.LIS
END REPEAT

Note that the repeat symbol is a SIR/XS name which allows curly brackets {} as part of the syntax. Command labels, that is labels used by the various SKIP command processing commands, also use curly brackets. In the unlikely event that a command label is also a repeat symbol, this can conflict as the DO REPEAT processor substitutes the name by the supplied parameter thus eliminating the brackets. In this instance, the substitution parameter must specify brackets in order to operate correctly. e.g.

DO REPEAT LAB = ${LABEL1}$
IFCOND (...)  SKIP LABEL1
.....
{LAB}
.....
END REPEAT

CIF

CIF operator  [arg1, [arg2]]

Specify a CIF command to begin a block of commands to process only if the stated condition is met. Terminate the block of commands with a CIF END command .

The general structure of the CIF command and sub-commands is:

CIF operator [ argument1 [, argument2 ]]
.   Commands conditionally
processed
CIF TRUE
.   Commands processed if not in skipping mode
CIF FALSE
.   Commands processed if in skipping mode
CIF TF
. Commands processed under all conditions
CIF END

CIF blocks can be nested within one another. The arguments can only be constants (strings in quotes or numbers). Parameter and global variable substitution into the CIF commands is allowed.

The CIF command specifies an operator and zero, one or two arguments. The arguments are often values of global variables or of parameters on the RUN, CALL, INCLUDE FILE and INCLUDE BUFFER commands that are substituted in when the command is processed. The arguments can be strings in quotes or numbers. For the relational tests, arguments must both be of the same type.
(Note that the form of this logical condition is different from VisualPQL logical expressions.)
The operators are:

CIF EQ arg1 , arg2 arg1 is equal to arg2
CIF NE arg1 , arg2 arg1 is not equal to arg2
CIF LT arg1 , arg2 arg1 is less than arg2
CIF LE arg1 , arg2 arg1 is less than or equal to arg2
CIF GT arg1 , arg2 arg1 is greater than arg2
CIF GE arg1 , arg2 arg1 is greater than or equal to arg2
CIF B arg1 arg1 is blank, i.e. no argument is specified
CIF NB arg1 arg1 is not blank, i.e. an argument is specified
CIF DEF global_variable global variable is defined
CIF NDEF global_variable global variable is not defined

The B and NB conditions test whether the remainder of the command line is blank or not.

The DEF and NDEF conditions test whether the global variable name specified is currently defined.

Conditional blocks can be nested to any level, i.e. a conditional block can be contained within another conditional block. The inner conditional block is executed only if it is encountered while commands are not being skipped by any outer conditional block.

Each CIF conditional command must have a corresponding CIF END command.

Consider the following:

CIF EQ <1>,3
.
. commands
.
CIF END

If these commands are run with a parameter list of (5), the commands within the conditional block are skipped and not processed. If the parameter list is (3), the commands within the conditional block are processed.

CIF FALSE | TRUE | TF

CIF  FALSE
CIF  TRUE
CIF  TF

The CIF sub-conditional commands alter the effect of the previous CIF conditional. The sub-condition affects commands up to the next sub-condition or until the end of the block specified by the matching CIF END command. If a CIF conditional command is encountered while commands are being skipped, that entire block is skipped, up to and including its matching CIF END command.

CIF FALSE: Stops statement skipping if the last condition was false. If the last condition was true, skipping either starts or continues.
CIF TRUE: Stops statement skipping if the previous condition was true. If the previous condition was false, skipping either starts or continues.
CIF TF: Stops skipping. Statements following CIF TF are always processed.

CIF END

CIF END

Terminates a conditional block. If this command terminates a nested conditional block, the condition of the previous block is restored, i.e. proper nesting occurs.

CIF EQ 3,3                 CIF EQ 3,4
.                          .
.  (processed)             .  (skipped)
.                          .
CIF FALSE                  CIF FALSE
.                          .
.  (skipped)               . (processed)
.                          .
CIF EQ 1,1                 CIF EQ 1,2
.                          .
.  (skipped)               . (skipped)
.                          .
CIF END                    CIF END
.                          .
.  (skipped)               .  (processed)
.                          .
CIF END                    CIF END

Input Flow Control

As an alternative to the CIF block structures, there are a number of commands that give the ability to skip commands to a named point depending on conditions.

Seven commands test logical conditions relating to global variables and the existence of procedure families and members. Logical test commands specify the condition being tested and skip when the condition is true.

The general syntax of the commands is:

IFxxxxxx condition SKIP label

The commands are:

IFCOND(condition) SKIP label: Test a specified condition.
IFMEMBER membname SKIP label: Tests for the existence of the named member and skips when the member exists. See member references for details on specifying member names.
IFNOTMEMBER membname SKIP label: Tests for the existence of the named member and skips when the member does not exist.
IFFAMILY famname SKIP label: Tests for the existence of the named family and skips when the family exists.
IFNOTFAMILY famname SKIP label: Tests for the existence of the named family and skips when the family does not exists.
IFGLOBAL global_varname SKIP label: Tests whether a global variable is initialized and executes the flow command when the global is initialized.
IFNOTGLOBAL global_varname SKIP label: Tests whether a global variable is initialized and executes the flow command when the global is not initialized.

The SKIP that follows a condition directs the flow of control to a named label. The name is used in the standard way on the SKIP.
Label a line in the input source by enclosing the name in braces {} starting in column one. Although this may look like a SIR non-standard name, it is not. Specify a SIR name inside these curly brackets. The label syntax of a curly bracket in column 1 predates non-standard names and has been retained for compatibility with existing procedures.

There are three variant SKIP commands:

SKIPBACK: Looks for a label from the beginning of the input source. Execution continues with the line following the specified statement label.
SKIPFORWARD: Looks for a label from the current command. Execution continues with the line following the specified statement label. SKIP is a synonym.
SKIPRETURN: Returns to the calling procedure. One input source can INCLUDE another procedure. SKIPRETURN returns control back up a level.
If there is no label on the command, control is transferred to the first statement following the calling command in the calling procedure.
If the command specifies a statement label, control is transferred to the beginning of the calling procedure, statement skipping begins and execution continues with the first command following the specified label. This is equivalent to a SKIPRETURN and SKIPBACK. There is no direct SKIPRETURN and SKIPFORWARD.

Labels need not be unique. The first match found is used. There is one predefined label, the {*}. When looking for a named label, the {*} label matches anything.

IFCOND

IFCOND (logical_condition) SKIP label
Tests the specified logical condition and skips when the condition is true. The command must fit on a single physical line. Specify the condition in parentheses. It consist of:

global variables treated as string variables
string constants (enclosed in single quotation marks)
numeric constants
global variable text substitution specifications (e.g. <gvarname>)
parentheses
operators:
- string ( + )
- numeric (EQ =, LT <, GT >, LE <= , GE >=, NE ><)
- logical (AND, OR, XOR)
- unary (+, - , NOT)

The IFCOND command tests the value in a global variable. So global variables can either be used for text substitution by enclosing them in angle brackets, or referenced as string variables. If a global variable enclosed in angle brackets is found, the value of the global variable is substituted in the text. If a string, not in quotes, is found, it is treated as a global variable. All globals are string variables.

To use globals to set numeric values, the global name must be enclosed in angle brackets. To use a global that contains a string value, either specify the name of the variable, without angle brackets or quotes, or specify quotes around the angle brackets.

IFCOND (gvar = 1) Mixed mode error since gvar is taken as a string
IFCOND (gvar = 'A') OK since gvar is a string
IFCOND (<gvar> = 1) Works if a numeric value assigned to gvar. Gives 'Unknown global' error, if an unquoted string is assigned to gvar.
IFCOND ('<gvar>' = 'A') OK since a string is being compared to a string.

For example:

IF (<gvar> EQ 1) SKIPBACK TOP
IF ('<gvar>' EQ 'A') SKIPBACK TOP
IF (GVAR EQ 'A' ) SKIPBACK TOP

EJECT

EJECT [ ODD | EVEN ]

Causes the output listing in batch to skip to a new page. The EJECT command is not listed.

ODD: Causes the listing to continue on the next odd numbered page.
EVEN: Causes the listing to continue on the next even numbered page.

ERROR LIMIT

ERROR LIMIT { number | NONE }

Specifies the maximum number of error messages that are written for a given task such as a Record Schema definition or VisualPQL program. Once the limit is reached, no more messages are printed. Syntax checking continues and the summary of error messages lists all errors encountered, including those detected after the limit was reached. The keyword NONE suppresses all error messages.

A task is defined by TASK NAME commands. If no tasks are defined, the whole session is a single task.

PRINT BACK

PRINT BACK [ ON | OFF ] [ SAVE | RESTORE]
 [ [NO]CALL     ]
 [ [NO]COMMANDS ]
 [ [NO]FORMAT   ]
 [ [NO]REMARK   ]
 [ [NO]REPEAT   ]
 [ [NO]SKIPPED  ]
 [ [NO]TASK     ]
 [ [NO]USER     ]

Controls the listing of procedure commands and remarks in the output file or on the screen. PRINT BACK can be used anywhere in a set of commands.

ON or OFF

SPACE

SPACE number

Generates the specified number of blank lines in the output listing.

STRING LENGTH

STRING LENGTH num

Sets the default length of implicitly declared string variables in VisualPQL or in the Record Schema. This is also the default length used for explicitly declared string variables where a length is not specified. The default string length is 32 characters.

WARNING LIMIT

WARNING LIMIT { number | NONE }

Specifies the maximum number of warning messages written to the output file for a given task. Once the limit is reached, no more warning messages are printed. Syntax checking continues and the summary of warning messages lists all warnings encountered, including those detected after the limit was reached.

The keyword NONE suppresses all warning messages.

A task is defined by TASK NAME commands. If no tasks are defined, the whole session is a single task.

Commands

This section describes commands that are not generic and can only be used outside VisualPQL programs or schema compilation in a similar way to running database utilities or batch data entry utilities. Commands are:

There are also a set of commands to manage members in a procedure file.

Note. Commands that are not valid VisualPQL are flagged as errors. RUN NAME and TASK NAME are recognised by the VisualPQL compiler and treated as indicating the end of that program.

ATTRIBUTE

ATTRIBUTE attribute_name FILENAME = "file_name"

Defines a SIR/XS name that is equivalent to the specified external filename. The file name must be enclosed in quotes. The file name can be any valid operating system file name, including any path, subdirectory or device specifications.

Once defined, the short attribute name may be used anywhere that a filename can be specified.

SIR/XS creates and uses an attribute for every filename that it uses. List the currently defined attributes from the Settings menu item. Define attributes with the ATTRIBUTE command, with the OPEN command in VisualPQL and from the Settings system menu.

COPY DIFFERENCE FILE

COPY DIFFERENCE FILE

If the session is connected to Master, requests that all databases connected at that time through that Master are written to disk so that updates are available for other processes.

PAGESIZE

PAGESIZE { lines_page | NOEJECT } , characters_line

Controls the size of the page if output is directed to an output listing file. The lines per page specification is the maximum number of printable lines on a page. The default is 60 lines per page including three lines at the top used for run and task headings. The NOEJECT keyword suppresses new page generation, i.e. the printing is continuous. The default characters per line is 121.

This has no effect on VisualPQL procedure output files that have their own PAGESIZE options.

PRINT FILE

PRINT FILE filename

Initiates the operating systems print routine for the named text file.

RUN MEMBER

RUN MEMBER membername:[E|T] (args)

Runs the named member with any specified positional parameters. Can be used to compile text (:T) members or execute saved (:E) executables.

If a member name without a suffix is RUN, and both a :T or :E version exist, the system determines which to run based on dates and times of last update.

RUN NAME

RUN NAME text

Sets a main title for the output listing. Ends VisualPQL or schema processing. Has no effect on error or warning counts.

SET
CLEAR

There are a number of system settings and parameters that can be set by command. The SET command sets the parameter to a particular value specified on the command.

The CLEAR command can be used with some parameters to reset back to the default.

The following parameters can be used:

CENY yyyy: Sets the year used for calculation of the default century when two digit years are input. When a two digit year is input, the system compares the input year with this parameter. If the parameter is less than the input, the century is set to the specified century. If the parameter is greater than or equal to the input, the century is set to the specified century plus 1.
The default is 1930.
To illustrate the calculation, assume the default setting of 1930. Then any input year in the range 00 - 29 is assigned a century of 20nn; any input year in the range 30 - 99 is assigned a century of 19nn.
All variables defined as dates are held internally as a number of days since the start of the Julian calendar on Oct 15 1582.
DEFINDEX indexname: Sets the default index on a table. Can be cleared.
DEFTABFILE tabfilename: Sets the default tabfile. Can be cleared.
DEFTABLE tablename: Sets the default table.
EDITOR editorname: Sets the name of the external editor. Can be cleared.
FAMILY familyname: Sets the default family name and password. The default family is also updated by commands that reference families and members.
LOADING .nn: Specify a value between .01 and .99.
Sets the loading factor used to determine how data blocks in the database are split as they become full. This setting affects Import and Reload of a database, VisualPQL retrieval updates and batch data input.
This can also be set by parameters on the VisualPQL RETRIEVAL command and on Batch Data Input commands.
MASTER name: Sets the use of Master. If a name is not specified, sets the Master to be the previously used Master.
CLEAR MASTER turns the use of Master off.
Equivalent execution statement parameter: MST=name
MEMBER [family[/password].member[/password]: Sets the default member name and password. Equivalent execution statement parameter: M=membername
OUTPUT filename: Sets a file as the standard output file. Can be cleared and, by default, output goes to the output window. Output is written to the standard output file by VisualPQL programs that WRITE to an unspecified file, and by utilities.
CLEAR OUTPUT cancels the filename of the default output file and output is then sent to the standard file (in batch mode) or output window (in interactive mode).
PROCFILE filename [PASSWORD password]: SET PROCFILE procfilename connects the named procedure file and disconnects the currently connected procedure file. Use the system attribute SYSPROC to connect the system procedure file. Use a blank filename to set the procfile to the procedure file of the current database.
If the procedure belongs to a database then it will inherit the DBA write level security password. Supplying the password on the SET PROCFILE command will attach the procfile and allow DBA level procfile commands DELETE/RENAME FAMILY and PWRITE FAMILY/PROCFILE.
SERVER NOOUTPUT: Controls output when running on the PQLServer. Can be used anywhere in the command stream to control selectively what output is made available for retrieval by the client. SET means that any output directed to standard output is thrown away. If this command is within a PQL program it would affect any compilation listing. Use the SERNOOUT function for execution time control.
SORTN nnnnnn: Sets the number of records expected to be sorted as a default. This is used where the default (number of records on the database) does not apply. Can also be set on VisualPQL Procedure commands.
WINPAGE: Output written to the output window is normally not paged. Set WINPAGE to put page breaks, headings, etc. in the output window for subsequent printing.

SHUTDOWN MASTER

SHUTDOWN MASTER [NOLOGONS] [password]

If the session is connected to Master, requests that Master to shutdown.

The keyword NOLOGONS specifies that the Master rejects any further client logons and warns existing clients that the shutdown is in progress. Master only completes the shutdown when there are no clients connected.

If Master was started with a password, specify the password on this command.

TASK NAME

TASK NAME text

Indicates the end of one task and the start of a new task. This ends any VisualPQL compilation or schema definition.

Can define a subheading printed below the main heading at the top of each page of the print back listing. TASK NAME can be specified as often as needed.

Procedure File Commands

There are a number of commands that can be used to manage a procedure file. Commands are:

Creating

A procedure file is automatically created when a database is created. You can create procedure files that are available for generic use and not part of a particular database with the CREATE PROCFILE command.

Procedure files may be protected by access restrictions defined at the operating system level. Users of an alternate procedure file must have operating system read access and may be allowed write access.

A procedure file created with a database will inherit the DBA write security level password. If this password is not specified on connecting to the database or procfile then some procedure file commands are not allowed.

Deleting

The procedure file is normally deleted along with the rest of the database files when the database is purged (deleted). When the Delete Database option is used from the Database- Recover menu, the procedure file can be deleted or can be left intact. If a database is reloaded and the procedure file already exists, the existing procedure file is used and any reloading of procedures is skipped. If a database is imported and the procedure file already exists, the existing procedure file is used and any imported procedures are added to it. If they have the same name as existing procedures, you are prompted as to whether to replace the existing with the import.

Member References

Many commands allow the specification of a member name or a list of member names and member names can be specified in a number of ways. A member can be uniquely referenced by its procedure file, family, member name and member type and both the family and member may be followed by a password. The various elements only have to be specified where used. For example, if the member does not have a password, it is not necessary to specify a blank password.

When specifying names with multiple elements, delimit the procedure file, family and member by full stops. Delimit passwords by a slash. For example:

CALL SYSPROC.PQL/FAMPASS.PROG1/MEMPASS:T

SYSPROC is the procedure file, PQL is the family with FAMPASS as the family password and PROG1 is the member name with MEMPASS as the member password. The :T indicates that this is a text member and is typically not required when referencing text members. Note that the procedure file specification is a name and this must have been associated with the required long filename, for example by a SET PROCFILE command.

If PROG1 has no passwords and is in the default procedure file, specify the following:

CALL PQL.PROG1

The default family is used if a family name is not specified. The initial default family is the SYSTEM family. After a member is accessed, the family of the last accessed member becomes the default family. The default family may be explicitly set with the SET FAMILY command.

The SYSTEM Family

The SYSTEM family is predefined. It may contain login scripts as well as other members.

Family References

Some commands operate on families rather than members. The above specification of names applies to specifying a family name, that is the family name can be preceded by a procedure file reference and followed by a password as required.

CREATE PROCFILE

CREATE PROCFILE filename

Creates a new procfile in the named file containing a SYSTEM family. In interactive mode if the file already exists then a prompt is displayed asking permission to overwrite. In Batch mode, any existing procfile is not overwritten

CONDENSE

CONDENSE

Condenses the procedure file removing unused space.

Use this command on a regular basis, especially after many members have been updated.

Copies all members in the procedure file to a temporary scratch file and then rebuilds a condensed procedure file.

CREATE FAMILY

CREATE FAMILY fname [ /password ]

Creates a family on the procedure file. A family is a group of members.

Specify a password if required.

DELETE FAMILY

DELETE FAMILY [ fname, fname, ... ]  [ /NOINFORM ]  [ /OK ]

Prompts for permission, then deletes specified families.

All members in the family are deleted. This is a DBA-only command.

NOINFORM: Suppresses informative messages for each family deleted.
OK: Suppresses the OK prompt for permission to delete the family.

DELETE MEMBER

DELETE MEMBER membername,... [DBA ]  [NOINFORM ] [OK ]

Deletes the specified member(s).

DBA: Deletes a member without requiring the member password. DBA security is required to do this.
NOINFORM: Suppresses message that member has been deleted.
OK: Deletes without requesting confirmation.

PLIST

PLIST fileid [ namelist ]
             [ FAMILY ]
             [ NOINFORM ]
             [ RULER ]
             [ UNNUMBERED ]
             [ UPPER ]

Writes a member to an external file in a suitable format for printing (with headers, paging, etc.).

fileid: Specify the output file. This is required.
namelist: A list of members or families to list. If the list is omitted, all members are listed.
FAMILY: FAMILY specifies that the namelist is a list of families. By default, the namelist is a list of members.
NOINFORM: Specifies that the number of lines listed is not reported. The default displays each member name and lines written.
RULER: Specifies that a ruler is displayed before the first line is listed. The default does not display a ruler.
UNNUMBERED: Specifies that the lines are not numbered. The default displays line numbers.
UPPER: UPPER specifies that the listing is in uppercase. The default displays in upper and lower case.

PREAD

PREAD fileid  [CONFIRM]
              [NOINFORM]
              [PUBLIC]
              [REPLACE]
              [REPORT]

Reads the contents of the specified file and saves the contents as members in the procedure file.

A message is displayed for each member. If the new member has the same name as a current member, a prompt is issued for permission to replace the current member.

The disk file must be in the correct format for a PREAD that is produced by PWRITE. The file can contain many members, and each member must have the following format:

PROCEDURE  family.member
.      text of procedure
END PROCEDURE

CONFIRM: Prompts to confirm the addition of any member.
NOINFORM: Suppresses the display of informative messages for each member read. Sets the REPORT keyword.
PUBLIC: Saves members as PUBLIC.
REPLACE: Suppresses the confirmation prompt when replacing existing members of the same name. When REPLACE is not specified, a prompt is issued for permission to replace the member.
REPORT: Gives the total number of added/replaced members after the entire file has been read. This is set on if NOINFORM is specified.

PROCEDURE command

PROCEDURE  [family[/password].]member[/password]
   [REPLACE] [PUBLIC]
.
.   text of member to be stored
.
END PROCEDURE

The text in the PROCEDURE block is saved in the named member. if this command appears in the input it saves a member and can be used to save a member during a batch run.

These commands can appear anywhere. If a PROCEDURE command appears within a VisualPQL program or Record Schema definition set, compilation is suspended until the END PROCEDURE command is encountered, upon which compilation is resumed.

REPLACE: Allows an existing member of the same name to be overwritten (replaced). The default is not to replace an existing member.
PUBLIC: If the family or member is protected by passwords, PUBLIC allows all users to execute the member but not to read or modify it.

PWRITE

PWRITE fileid  [ mlist ]  [ FAMILY ]  [ NOINFORM ]  [ NOTIMES ]

Writes the specified member(s) to the named file. If no members are specified, writes the entire Procedure File.

FAMILY: Specifies that the list is a list of family names and that all members of the specified families are written to the fileid.
NOINFORM: Normally a list of members written to the file is produced. NOINFORM suppresses that list.
NOTIMES: Normally time and date stamps are written to the file for each procedure. NOTIMES suppresses this which creates a file that can be read by earlier versions of SIR.

RENAME

RENAME [family.]member1 [family.]member2 [[NO]PUBLIC]

Renames member1 to member2. Member1 no longer exists in the procedure file.

Rename a member to itself to alter the password or the PUBLIC option. Specify the old password on member1 and the new password on member2. PUBLIC allows people to run a member without knowing the member password.

RENAME FAMILY

RENAME FAMILY family1 family2

Renames family1 to family2. Family1 no longer exists in the procedure file, all members of family1 are now in family2. Rename a family to itself to alter the password. Specify the old password on family1 and the new password on family2.

Commands

Comments and Remarks

Global Variables

Global variables at run time

GLOBAL

GCOMPUTE

System Globals

Parameter Substitution

INCLUDE BUFFER | FILE | MEMBER

FINISH

PEND

DO REPEAT

Note:

TO Keyword

Concatenation

Multiple Repeat Symbols

Other Examples

CIF

CIF FALSE | TRUE | TF

CIF END

Input Flow Control

IFCOND

EJECT

ERROR LIMIT

PRINT BACK

SPACE

STRING LENGTH

WARNING LIMIT

Commands

ATTRIBUTE

COPY DIFFERENCE FILE

PAGESIZE

PRINT FILE

RUN MEMBER

RUN NAME

SETCLEAR

SHUTDOWN MASTER

TASK NAME

Procedure File Commands

Creating

Deleting

Member References

The SYSTEM Family

Family References

CREATE PROCFILE

CONDENSE

CREATE FAMILY

DELETE FAMILY

DELETE MEMBER

PLIST

PREAD

PROCEDURE command

PWRITE

RENAME

RENAME FAMILY

SET
CLEAR